Extensió:Scribunto/Manual de referència de Lua

Aquest manual documenta Lua tal com s'utilitza a MediaWiki amb l'extensió Scribunto . Algunes parts es deriven del Manual de referència de Lua 5.1, que està disponible sota la llicència MIT.

Introducció

Primers passos

En un wiki MediaWiki amb Scribunto habilitat, creeu una pàgina amb un títol que comenci amb Module:, per exemple "Module:Bananas". A aquesta pàgina nova, copieu el text següent:

local p = {} --p representa al paquet

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

return p

Deseu-ho. Després en una altra pàgina (no en un mòdul), com en una pàgina de proves, escriviu:

{{#invoke:Bananas|hello}}

Excepte que hàgiu de substituir "Bananas" amb el que hàgiu anomenat el vostre mòdul. Això cridarà la funció "hello" exportada des d'aquest mòdul. {{#invoke:Bananas|hello}} se substituirà pel text que la funció retorna, en aquest cas, "Hello, world!"

Generalment, és una bona idea invocar el codi Lua des del context d’una plantilla. Això vol dir que, des de la perspectiva d’una pàgina que fa la crida, la sintaxi és independent de si la lògica de la plantilla s’implementa en Lua o en un wikitext. També evita la introducció de sintaxi complexa addicional a l’espai de noms de contingut d’un wiki.

Estructura de mòdul

El mòdul en si ha de retornar una taula Lua que contingui les funcions que poden ser cridades per {{#invoke:}}. Generalment, com s'ha mostrat anteriorment, es declara una variable local que conté una taula, s'afegeixen funcions a aquesta taula i la taula es retorna al final del codi del mòdul.

Les funcions que no s'afegeixin a aquesta taula, siguin locals o globals, no seran accessibles per {{#invoke:}}, però les globals podrien ser accessibles des d'altres mòduls carregats mitjançant require(). Generalment, és un bon estil que el mòdul declari totes les funcions i variables locals.

Accés a paràmetres des de wikitext

Les funcions cridades per {{#invoke:}} rebran un únic paràmetre, que és un objecte frame. Per accedir als paràmetres passats a {{#invoke:}}, el codi normalment utilitzarà la taula args d'aquest objecte frame. També és possible accedir als paràmetres passats a la plantilla que conté {{#invoke:}} mitjançant frame:getParent() i accedint als args d'aquest frame. Aquest objecte frame també s'utilitza per accedir a funcions específiques del context de l'analitzador wikitext, com ara cridar funcions d'anàlisi, expandir plantilles i expandir cadenes wikitext arbitràries.

Retorn de text

La funció del mòdul normalment hauria de retornar una sola cadena; els valors retornats es passaran a través de tostring() i després es concatenaran sense separador. Aquesta cadena s'incorpora al text wiki com a resultat de {{#invoke:}}.

En aquest punt de l'anàlisi de la pàgina, les plantilles ja s'han expandit, les funcions d'anàlisi i les etiquetes d'extensió ja s'han processat i les transformacions prèvies al desament (és a dir, l'expansió de la titlla de signatura, el truc de la barra vertical, etc.) ja s'han produït. Per tant, el mòdul no pot utilitzar aquestes funcions al seu text de sortida. Per exemple, si un mòdul retorna "Hello, [[world]]! {{welcome}}", en la pàgina es llegirà Hello, world! {{welcome}}.

D'altra banda, subst es gestiona en una etapa anterior del processament, de manera que amb {{subst:#invoke:}} només es processaran altres intents de substitució. Com que la substitució fallida romandrà al wikitext, es processarà a la següent edició. Generalment, això s'hauria d'evitar.

Documentació de mòdul

Scribunto permet documentar els mòduls associant-los automàticament amb una pàgina de documentació de wikitext; per defecte, la subpàgina "/doc" del mòdul s'utilitza per a aquest propòsit i es transclou per sobre del codi font del mòdul a la pàgina del mòdul. Per exemple, la documentació de "Module:Bananas" seria a "Module:Bananas/doc".

Això es pot configurar mitjançant els següents missatges de sistema :

• scribunto-doc-page-name — Estableix el nom de la pàgina utilitzada per a la documentació. El nom del mòdul (sense el prefix Module:) es passa com a $1. A l'espai de noms Mòdul, les pàgines especificades aquí s'interpretaran com a wikitext en lloc de font Lua i no es poden utilitzar amb {{#invoke:}}. El valor per defecte és "Mòdul:$1/doc", és a dir, la subpàgina /doc del mòdul. Tingueu en compte que les funcions d'anàlisi i altres expansions de claus no es poden utilitzar en aquest missatge.
• scribunto-doc-page-does-not-exist — Missatge que es mostra quan la pàgina doc no existeix. El nom de la pàgina es passa com a $1. El valor per defecte és buit.
• scribunto-doc-page-show — Missatge que es mostra quan la pàgina doc existeix. El nom de la pàgina es passa com a $1. El valor per defecte és transcloure la pàgina de documentació.
• scribunto-doc-page-header — Capçalera que es mostra en visualitzar ella mateixa la pàgina de documentació. El nom del mòdul (amb el prefix Mòdul:) que es documenta es passa com a $1. El valor per defecte simplement mostra una breu explicació en cursiva.

Tingueu en compte que els mòduls no es poden categoritzar directament. Les insercions de categories es poden col·locar a la pàgina de documentació dins de les etiquetes ‎‎<includeonly>...‎</includeonly>, on s'aplicaran al mòdul quan la pàgina de documentació es transclogui a la pàgina del mòdul.

Canviar el nom o moure mòduls

Per canviar el nom o moure un mòdul, utilitzeu l'enllaç Reanomena a la barra lateral Eines. Haureu de moure tant el mòdul en si com la subpàgina que conté la seva documentació.

Redireccions

MediaWiki version:

≥ 1.42 Gerrit change 574086

Des de la versió 1.42, Scribunto reconeix una sintaxi particular per a les redireccions (de manera que es ressalten a les pàgines especials, apareixen a Special:WhatLinksHere, etc.), i també produeix redireccions en canviar el nom/moure un mòdul, de manera similar a com funciona el canvi de nom de les pàgines wikitext (abans d'això, els canvis de nom de mòduls no deixaven redireccions, ara es necessiten drets addicionals per suprimir la redirecció).

Per crear manualment una redirecció de mòdul, utilitzeu la sintaxi següent (que és codi Lua vàlid i funcionava com una redirecció fins i tot abans de la versió 1.42, però sense que MediaWiki la reconegués com a tal):

return require [[Module:Foo]]

Substituïu Foo pel nom del mòdul al qual voleu redirigir.

Tingueu en compte que altres variacions de sintaxi Lua igualment vàlides (per exemple, l'ús de cometes en lloc de claudàtors, l'ús de parèntesis al voltant del paràmetre require o fins i tot variacions d'espais en blanc) encara no són reconegudes per MediaWiki com a redireccions.

Llenguatge Lua

Noms, paraules reservades i símbols

Un nom (també anomenat identificador) a Lua pot ser qualsevol cadena de lletres, xifres i subratllats, que no comenci amb una xifra. Els noms distingeixen entre majúscules i minúscules; "foo", "Foo" i "FOO" són noms diferents.

Les paraules clau següents estan reservades i no es poden utilitzar com a noms:

• and
• break
• do
• else
• elseif
• end
• false
• for
• function
• if
• in
• local
• nil
• not
• or
• repeat
• return
• then
• true
• until
• while

Els noms que comencen amb un subratllat seguit de lletres majúscules es reserven per a variables globals internes de Lua.

Símbols utilitzats són:

• #
• %
• (
• )
• *
• +
• ,
• -
• --
• .
• ..
• ...
• /
• :
• ;
• <
• <=
• =
• ==
• >
• >=
• [
• ]
• ^
• {
• }
• ~=

Comentaris

Un comentari comença amb un -- a qualsevol lloc fora d'una cadena. Si el -- va seguit immediatament d'un claudàtor d'obertura, el comentari continua fins al claudàtor de tancament corresponent; en cas contrari, el comentari s'estén fins al final de la línia actual.

-- Un comentari a Lua comença amb un guionet doble i va fins al final de la línia.
--[[ Les cadenes i els comentaris de diverses línies
estan adornats amb claudàtors dobles. ]]
--[=[ Comentaris com aquest poden tenir altres --[[comentaris]] imbricats. ]=]
--[==[ Comentaris com aquest poden tenir altres
      --[===[ llargs --[=[comentaris]=] --imbricats
        ]===] diverses vegades, fins i tot si tots ells
      --[[ no estan delimitats amb claudàtors coincidents! ]===]
  ]==]

Tipus de dades

Lua ​​és un llenguatge de tipus dinàmic, la qual cosa significa que les variables i els arguments de funció no tenen cap tipus, només els valors que se'ls assignen. Tots els valors tenen un tipus.

Lua ​​té vuit tipus de dades bàsics, però només sis són rellevants per a l'extensió Scribunto. La type() retornarà el tipus d'un valor.

La funció tostring() convertirà un valor en una cadena. La funció tonumber() convertirà un valor en un nombre si és possible, i en cas contrari retornarà nil. No hi ha funcions explícites per convertir un valor a altres tipus de dades.

Els nombres es converteixen automàticament en cadenes quan s'utilitzen on s'espera una cadena, per exemple, quan s'utilitzen amb l'operador de concatenació. Les cadenes reconegudes per tonumber() es converteixen automàticament en nombres quan s'utilitzen amb operadors aritmètics. Quan s'espera un valor booleà, tots els valors que no siguin nil i false es consideren true.

nil

"nil" és el tipus de dades de nil, que existeix per representar l'absència d'un valor.

nil no es pot utilitzar com a clau en una taula, i no hi ha cap diferència entre una clau de taula no assignada i una clau amb un valor nil assignat.

Quan es converteix a una cadena, el resultat és "nil". Quan es converteix a booleà, nil es considera false.

Nota: Lua fa una distinció entre nil i res en absolut en algunes situacions limitades. Per exemple, tostring(nil) retorna "nil", però tostring() genera un error, ja que el primer paràmetre és obligatori. Aquesta distinció és particularment rellevant per a la funció select().

booleà

Els valors booleans són true i false.

Quan es converteixen a una cadena, el resultat és "true" o "false".

A diferència de molts altres llenguatges, els valors booleans no es poden convertir directament en nombres. I a diferència de molts altres llenguatges, només false i nil es consideren false per a la conversió booleana; el número 0 i la cadena buida es consideren true.

cadena de caràcters

Les cadenes Lua es consideren una sèrie de bytes de 8 bits; depèn de l'aplicació interpretar-les en qualsevol codificació particular.

Els literals de cadena poden estar delimitats per cometes simples o dobles (' o "); com JavaScript i a diferència de PHP, no hi ha cap diferència entre els dos. Es reconeixen les següents seqüències d'escapament:

• \a (campana, byte 7)
• \b (retrocés, byte 8)
• \t (tabulació horitzontal, byte 9)
• \n (salt de línia, byte 10)
• \v (tabulació vertical, byte 11)
• \f (salt de pàgina, byte 12)
• \r (retorn de carro, byte 13)
• \" (cometes dobles, byte 34)
• \' (cometes simples, byte 39)
• \\ (barra invertida, byte 92)

També es pot incloure un salt de línia literal en una cadena precedint-la d'una barra invertida. Els bytes també es poden especificar mitjançant una seqüència d'escapada '\ddd', on ddd és el valor decimal del byte en el rang de 0 a 255. Per incloure caràcters Unicode mitjançant seqüències d'escapada, cal especificar els bytes individuals per a la codificació UTF-8; en general, serà més senzill introduir els caràcters Unicode directament.

Les cadenes literals també es poden definir mitjançant claudàtors llargs. Un claudàtor llarg d'obertura consisteix en un claudàtor d'obertura seguit de zero o més signes igual seguit d'un altre claudàtor d'obertura, per exemple, [[, [=[ o [=====[. El ​​claudàtor llarg d'obertura ha de coincidir amb el claudàtor llarg de tancament corresponent, per exemple, ]], ]=] o ]=====]. Com a cas especial, si un claudàtor llarg d'obertura va seguit immediatament d'un salt de línia, el salt de línia no s'inclou a la cadena, sinó que es conserva un salt de línia just abans del claudàtor llarg de tancament. Les cadenes delimitades per claudàtors llargs no interpreten les seqüències d'escapament.

-- Aquesta cadena llarga
foo = [[
bar\tbaz
]]

-- és equivalent a aquesta cadena delimitada per cometes
foo = 'bar\\tbaz\n'

Tingueu en compte que totes les cadenes es consideren true quan es converteixen en booleans. Això és diferent de la majoria dels altres llenguatges, on la cadena buida es considera normalment false.

número

Lua només té un tipus numèric, que normalment es representa internament com un valor de coma flotant de doble precisió de 64 bits. En aquest format, els enters entre -9007199254740991 (-2⁵³ + 1) i 9007199254740991 (2⁵³ - 1) es poden representar exactament; els nombres més grans i els nombres amb una part fraccionària poden patir errors d'arrodoniment.

Les constants numèriques s'especifiquen mitjançant un punt (.) com a separador decimal i sense separadors d'agrupació, per exemple, 123456.78. Els números també es poden representar mitjançant la notació E sense espais, per exemple, 1.23e-10, 123.45e20 o 1.23E+5. Els enters també es poden especificar en notació hexadecimal mitjançant un prefix 0x, per exemple, 0x3A.

Un grapat de valors numèrics es gestionen d'una manera especial:

• Infinit positiu i negatiu, que resulten ser més grans o més petits que qualsevol altre nombre, respectivament (excepte els NaN - vegeu més avall). S'hi pot accedir de dues maneres: a través de la biblioteca matemàtica, com a math.huge i -math.huge, o mitjançant operacions numèriques com ara 1/0 i -1/0.
• Lua ​​ocasionalment distingeix 0 i -0 (vegeu l'IEEE 754 per obtenir més informació sobre zeros amb signe). 0 i -0 són estrictament equivalents per a gairebé tots els propòsits, però es comporten de manera diferent en un petit nombre d'operacions numèriques (per exemple, 1/0 retorna infinit, mentre que 1/-0 retorna infinit negatiu). La distinció també afecta les conversions de nombre a cadena (i viceversa).
• NaN positiu i negatiu (que significa "No és un Número"). No es proporciona cap constant per a cap d'aquests, però 0/0 s'avalua com a NaN negatiu. Tingueu en compte que tots dos NaN tenen la qualitat única que qualsevol comparació que els impliqui s'avalua com a false (cosa que significa que ni tan sols s'avaluen com a iguals a si mateixos). L'única distinció pràctica entre els dos és la conversió de tipus des de i cap a una cadena (vegeu més avall).

Tingueu en compte que tots els nombres (inclosos 0, -0, els infinits i NaN) es consideren true quan es converteixen a booleans. Això és diferent de la majoria d'altres llenguatges, on 0 normalment es considera false. Quan es converteixen a una cadena, els nombres finits es representen en decimal, i en notació E si són 10¹⁴ o més (per exemple, "1e+14"); els infinits són "inf" i "-inf"; i els NaN són "nan" i "-nan".

Error conegut: l'intèrpret Lua tractarà totes les instàncies de 0 i -0 com la primera de les dues que es trobi quan es compila l'script, cosa que significa que els valors de retorn de tostring(0), 1/-0 (i així successivament) es veuen afectats per on es produeixen al codi. Això pot causar resultats inesperats, sobretot si totes les instàncies de 0 es converteixen a "-0" en retornar. Si cal, es pot evitar això generant valors zero utilitzant tonumber("0") i tonumber("-0"), que no sembla causar ni estar afectat pel problema. Vegeu [1].

taula

Les taules Lua són matrius associatives, de manera molt semblant a les matrius PHP i els objectes JavaScript.

Les taules es creen mitjançant claus. La taula buida és {}. Per omplir els camps en crear-los, es pot incloure una llista d'especificadors de camp separats per comes i/o punts i coma entre les claus. Aquests prenen qualsevol de les diverses formes:

• [expression1] = expression2 utilitza el (primer) valor de expression1 com a clau i el (primer) valor de expression2 com a valor.
• name = expression és equivalent a ["name"] = expression
• expression és aproximadament equivalent a [i] = expression, on i és un enter que comença a 1 i que s'incrementa amb cada especificació de camp d'aquesta forma. Si aquest és l'últim especificador de camp i l'expressió té diversos valors, s'utilitzen tots els valors; en cas contrari, només es conserva el primer.

S'accedeix als camps d'una taula mitjançant la notació de claudàtors, p. ex. table[key]. Les claus de cadena que siguin noms vàlids, també permetent d'accedir-hi amb la notació de punts, p. ex. table.key és equivalent a table['key']. Per cridar una funció que és un valor de la taula es pot utilitzar la notació de dos punts; per exemple, table:func( ... ), que és equivalent a table['func']( table, ... ) o table.func( table, ... ).

Una matriu (també anomenada seqüència o llista) és una taula amb valors diferents de nuls per a tots els enters positius de l'1 a N i cap valor (nil) per a tots els enters positius superiors a N. Moltes funcions Lua només operen amb matrius i ignoren les claus que no siguin enters positius.

A diferència de molts altres llenguatges com PHP o JavaScript, qualsevol valor excepte nil i NaN es pot utilitzar com a clau i no es realitza cap conversió de tipus. Tots aquests són vàlids i diferents:

-- Crea la taula
t = {}
t["foo"] = "foo"
t.bar = "bar"
t[1] = "un"
t[2] = "dos"
t[3] = "tres"
t[12] = "el número dotze"
t["12"] = "la cadena dotze"
t[true] = "true"
t[tonumber] = "sí, fins i tot les funcions poden ser claus de taula"
t[t] = "sí, una taula també pot ser una clau de taula, fins i tot en si mateixa."

-- Això crea una taula aproximadament equivalent a l'anterior
t2 = {
    ["foo"] = "foo",
    bar = "bar",
    "un",
    "dos",
    [12] = "el número dotze",
    ["12"] = "la cadena dotze",
    "tres",
    [true] = "true",
    [tonumber] = "sí, fins i tot les funcions poden ser claus de taula",
}
t2[t2] = "sí, una taula també pot ser una clau de taula, fins i tot en si mateixa."

De la mateixa manera, qualsevol valor excepte nil es pot emmagatzemar com a valor en una taula. Emmagatzemar nil és equivalent a suprimir la clau de la taula, i accedir a qualsevol clau que no s'hagi definit donarà lloc a un valor nil.

Tingueu en compte que les taules no es copien mai implícitament a Lua; si es passa una taula com a argument en la funció i la funció manipula les claus o els valors de la taula, aquests canvis seran visibles a l'autor de la crida.

Quan es converteix en una cadena, el resultat habitual és "table", però es pot anul·lar mitjançant el metamètode __tostring. Fins i tot la taula buida es considera com un booleà true.

funció

Les funcions a Lua són valors de primera classe: es poden crear de forma anònima, passar-les com a arguments, assignar-les a variables, etc.

Les funcions es creen mitjançant la paraula clau function i es criden mitjançant parèntesis. El sucre sintàctic està disponible per a funcions amb nom, funcions locals i funcions que actuen com a funcions membres d'una taula. Vegeu Declaracions de funcions i Crides de funcions a continuació per obtenir més informació.

Les funcions Lua són clausures, és a dir, que mantenen una referència a l'àmbit en què es declaren i es poden accedir i manipular les variables en aquest àmbit.

Igual que les taules, si una funció s'assigna a una variable diferent o es passa com a argument a una altra funció, continua sent el mateix "objecte de funció" subjacent el que es cridarà.

Quan es converteix en una cadena, el resultat és "function".

Tipus de fitxers no admesos

El tipus userdata s'utilitza per contenir valors opacs per a extensions a Lua escrites en altres llenguatges; per exemple, un userdata es pot utilitzar per contenir un punter o estructura C. Per permetre l'ús de Scribunto en entorns d'allotjament on no es permet el codi compilat personalitzat, no s'utilitzen aquestes extensions.

El tipus thread (fil) representa els identificadors de les corutines, que no estan disponibles a la caixa de proves de Scribunto.

Valors externs (Upvalues)

Hi ha un límit estricte de 60 valors externs únics als quals es pot accedir dins d'una funció. Un valor extern és un valor declarat fora d'una funció i utilitzat dins d'ella. Compten com a valors externs:

• variables (una taula amb molts elements compta com un sol valor extern)
• funcions (només les que es criden directament des de la funció en qüestió, no les seves dependències)

Una violació del límit pot ser provocada per l'ús d'aquesta variable o funció, no per la seva mera presència o disponibilitat. L'accés repetit al mateix valor extern no esgota més el límit.

Metataules

Cada taula pot tenir una taula associada coneguda com a metataula. Els camps de la metataula són utilitzats per alguns operadors i funcions per especificar un comportament diferent o de reserva per a la taula. Es pot accedir a la metataula d'una taula mitjançant la funció getmetatable() i definir-la amb la funció setmetatable().

Quan s'accedeix a les seves metafuncions, els camps de la metataula s'accedeixen com si es fes amb rawget().

Els camps de la metataula que afecten la taula en si són:

__index

Això s'utilitza quan un accés a una taula t[key] retornaria nil. Si el valor d'aquest camp és una taula, l'accés es repetirà en aquesta taula, és a dir, __index[key] (que pot invocar el __index de la metataula d'aquesta taula). Si el valor d'aquest camp és una funció, la funció es cridarà com a __index( t, key ). La funció rawget() ignora aquest metamètode.

__newindex

Això s'utilitza quan s'assigna una clau a una taula t[key] = value on rawget( t, key ) retornaria nil. Si el valor d'aquest camp és una taula, l'assignació es farà a aquesta taula, és a dir, __newindex[key] = value (que pot invocar el __newindex de la metataula d'aquesta taula). Si el valor d'aquest camp és una funció, la funció es cridarà com a __newindex( t, key, value ). La funció rawset() ignora aquest metamètode.

__call

Això s'utilitza quan la sintaxi de crida de funció s'utilitza en una taula, t( ··· ). El valor ha de ser una funció, que es crida com a alguna cosa semblant a __call( t, ··· ).

__mode

Això s'utilitza per fer taules que continguin referències febles. El valor ha de ser una cadena. Per defecte, qualsevol valor que s'utilitzi com a clau o com a valor en una taula no es recollirà per brossa. Però si aquest metacamp conté la lletra 'k', les claus poden ser recollides per brossa si no hi ha referències no febles, i si conté 'v', els valors poden ser-ho; en qualsevol cas, tant la clau com el valor corresponents s'eliminen de la taula. Tingueu en compte que el comportament no està definit si aquest camp s'altera després que la taula s'utilitzi com a metataula.

Altres camps de metataula inclouen:

• __add^†
• __sub^†
• __mul^†
• __div^†
• __mod^†
• __pow^†
• __unm
• __concat^†
• __eq^‡
• __lt^‡
• __le^‡
• __pairs
• __ipairs
• __metatable^*
• __tostring

^† Per als operadors binaris, Lua mira primer la metataula de l'argument esquerre (si n'hi ha) i després la de la dreta quan busca un metamètode a utilitzar.

^‡ Per als operadors relacionals, el metamètode només s'utilitza si s'especifica la mateixa funció a les metataules d'ambdós arguments. Funcions anònimes diferents, fins i tot amb un cos i un tancament idèntics, poden no considerar-se iguals.

^* __metatable afecta tant a getmetatable() com a setmetatable()

Nota: A Lua, totes les cadenes també comparteixen una única metataula, en què __index fa referència a la taula string. Aquesta metataula no és accessible a Scribunto, ni tampoc la taula string a la qual es fa referència; la taula de cadenes disponible per als mòduls és una còpia.

Variables

Les variables són llocs on s'emmagatzemen valors. Hi ha tres tipus de variables a Lua: variables globals, variables locals i camps de taula.

Un nom representa una variable global o local (o un argument de funció, que és simplement un tipus de variable local). Se suposa que les variables són globals tret que es declarin explícitament com a locals mitjançant la paraula clau local. Qualsevol variable a la qual no se li hagi assignat un valor es considera que té un valor nil.

Les variables globals s'emmagatzemen en una taula Lua estàndard anomenada environment (entorn); aquesta taula sovint està disponible com a variable global _G. És possible establir una metataula per a aquesta taula de variables globals; els metamètodes __index i __newindex es cridaran per a accessos i assignacions a variables globals igual que ho farien per a accessos i assignacions a camps de qualsevol altra taula.

Es pot accedir a l'entorn d'una funció mitjançant la funció getfenv() i canviar-lo mitjançant la funció setfenv(); a Scribunto, aquestes funcions estan molt restringides si és que estan disponibles.

Les variables locals tenen un àmbit lèxic; vegeu Declaracions de variables locals per a més detalls.

Expressions

Una expressió és quelcom que té valors: literals (nombres, cadenes, true, false, nil), declaracions de funcions anònimes, constructors de taules, referències de variables, crides de funcions, l'expressió vararg, expressions entre parèntesis, operadors unaris aplicats a expressions i expressions combinades amb operadors binaris.

La majoria d'expressions tenen un valor; les crides de funcions i l'expressió vararg poden tenir qualsevol número. Tingueu en compte que si poseu una crida de funció o una expressió vararg entre parèntesis, es perdrà tot excepte el primer valor.

Les llistes d'expressions són llistes d'expressions separades per comes. Totes excepte l'última expressió es forcen a tenir un valor (eliminant valors addicionals o utilitzant nil si l'expressió no té valors); tots els valors de l'última expressió s'inclouen als valors de la llista d'expressions.

Operadors aritmètics

Lua admet els operadors aritmètics habituals: suma, resta, multiplicació, divisió, mòdul, potenciació i negació.

Quan tots els operands són nombres o cadenes per a les quals tonumber() retorna un valor diferent de zero, les operacions tenen el seu significat habitual.

Si algun dels operands és una taula amb un metamètode adequat, es cridarà el metamètode.

Operador	Funció	Exemple	Metamètode	Notes
+	Suma	a + b	__add
-	Resta	a - b	__sub
*	Multiplicació	a * b	__mul
/	Divisió	a / b	__div	la divisió per zero no és un error; es retornarà NaN o infinit
%	Mòdul	a % b	__mod	definit com a a % b == a - math.floor( a / b ) * b
^	Potenciació	a ^ b	__pow	Es permeten exponents no enters
-	Negació	-a	__unm

Operadors relacionals

Els operadors relacionals a Lua són ==, ~=, <, >, <=, i >=. El resultat d'un operador relacional sempre és un booleà.

La igualtat (==) primer compara els tipus dels seus operands; si són diferents, el resultat és false. Després compara els valors: nil, booleà, número i cadena es comparen de la manera esperada. Les funcions són iguals si es refereixen exactament al mateix objecte de funció; function() end == function() end retornarà false, ja que està comparant dues funcions anònimes diferents. Les taules es comparen per defecte de la mateixa manera, però això es pot canviar mitjançant el metamètode __eq.

La desigualtat (~=) és la negació exacta de la igualtat.

Per als operadors d'ordenació, si tots dos són números o tots dos són cadenes, es comparen directament. A continuació, es comproven els metamètodes:

• a < b utilitza __lt
• a <= b utilitza __le si està disponible, o si __lt està disponible llavors es considera equivalent a not ( b < a )
• a > b es considera equivalent a b < a
• a >= b es considera equivalent a b <= a

Si els metamètodes necessaris no estan disponibles, es genera un error.

Operadors lògics

Els operadors lògics són and, or i not. Tots utilitzen la interpretació estàndard on nil i false es consideren false i qualsevol altra cosa es considera true.

Per a and, si l'operand esquerre és false es retorna false, i el segon operand no s'avalua; en cas contrari, es retorna el segon operand.

Per a or, si l'operand esquerre es considera true es retorna true i el segon operand no s'avalua; en cas contrari, es retorna el segon operand.

Per a not, el resultat sempre és true o false.

Tingueu en compte que per a and i or hi ha un circuit curt. Per exemple, foo() or bar() només cridarà bar() si foo() retorna false o nil com a primer valor.

Operador de concatenació

L'operador de concatenació són dos punts, utilitzats com a .. b. Si tots dos operands són nombres o cadenes, es converteixen en cadenes i es concatenen. En cas contrari, si hi ha un metamètode __concat disponible, s'utilitza. En cas contrari, es genera un error.

Tingueu en compte que les cadenes Lua són immutables i Lua no proporciona cap mena de "constructor de cadenes", de manera que un bucle que repeteixi a = a .. b haurà de crear una nova cadena per a cada iteració i, finalment, recollir les cadenes antigues. Si cal concatenar moltes cadenes, pot ser més ràpid utilitzar string.format() o inserir totes les cadenes en una seqüència i utilitzar table.concat() al final.

Operador de longitud

L'operador de longitud és #, utilitzat com a #a. Si a és una cadena, retorna la longitud en bytes. Si a és una taula de seqüència, retorna la longitud de la seqüència.

Si a és una taula que no és una seqüència, #a pot retornar 0 o qualsevol valor N tal que a[N] no sigui nil i a[N+1] sigui nil, fins i tot si hi ha valors diferents de nil en índexs més alts. Per exemple,

-- Això no és una seqüència, perquè a[3] és ''nil'' i a[4] no ho és.
a = { 1, 2, nil, 4 }

-- Això pot donar com a resultat 2 o 4.
-- I això pot canviar fins i tot si la taula no es modifica.
mw.log( #a )

Precedència dels operadors

Precedència d'operadors o ordre d'operacions de Lua, de més alt a més baix:

1. ^
2. not # - (negació)
3. * / %
4. + - (resta)
5. ..
6. < > <= >= ~= ==
7. and
8. or

Dins d'un nivell de precedència, la majoria dels operadors binaris són associatius a l'esquerra, és a dir, a / b / c s'interpreta com a (a / b) / c. La potenciació i la concatenació són associatives a la dreta, és a dir, a ^ b ^ c s'interpreta com a a ^ (b ^ c).

Crides de funcions

Les crides de funcions de Lua s'assemblen a les de la majoria d'altres llenguatges: un nom seguit d'una llista d'arguments entre parèntesis:

func( llista-d'expressions )

Com és habitual amb les llistes d'expressions a Lua, l'última expressió de la llista pot proporcionar diversos valors d'arguments.

Si la funció es crida amb menys valors a la llista d'expressions que arguments a la definició de la funció, els arguments addicionals tindran un valor nil. Si la llista d'expressions conté més valors que arguments, els valors sobrants es descarten. També és possible que una funció accepti un nombre variable d'arguments; vegeu Declaracions de funcions per a més detalls.

Lua ​​també permet la crida directa d'un valor de retorn de funció, és a dir, func()(). Si es necessita una expressió més complexa que un accés variable per determinar la funció que s'ha de cridar, es pot utilitzar una expressió entre parèntesis en lloc de l'accés variable.

Lua ​​té sucre sintàctic per a dos casos comuns. El primer és quan s'utilitza una taula com a objecte i la funció s'ha de cridar com a mètode sobre l'objecte. La sintaxi

taula:nom( llista-d'expressions )

és exactament equivalent a

taula.nom( taula, llista-d'expressions )

El segon cas comú és el mètode de Lua d'implementar arguments amb nom passant una taula que conté les correspondències nom-valor com a únic argument posicional de la funció. En aquest cas, es poden ometre els parèntesis al voltant de la llista d'arguments. Això també funciona si s'ha de passar una única cadena literal a la funció. Per exemple, les crides

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

són equivalents a

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

Aquestes es poden combinar; les crides següents són equivalents:

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

Declaracions de funcions

La sintaxi per a la declaració de funcions és com aquesta:

function nameoptional ( var-listoptional )
    bloc
end

Totes les variables de var-list són locals a la funció, amb valors assignats des de la llista d'expressions a la crida de funció. Es poden declarar variables locals addicionals dins del bloc.

Quan es crida la funció, les instruccions del bloc s'executen després que es creïn les variables locals corresponents a var-list i se'ls assignin valors. Si s'arriba a una instrucció return, se surt del bloc i els valors tornats per l'expressió de la crida de la funció són els que dona la instrucció return. Si l'execució arriba al final del bloc de la funció sense trobar una instrucció return, el resultat de l'expressió de crida a la funció té valors zero.

Les funcions Lua són tancaments lèxics. Una expressió comuna és declarar les variables "estàtiques privades" com a locals en l'àmbit on es declara la funció. Per exemple,

-- Això retorna una funció que afegeix un nombre al seu argument
function makeAdder( n )
    return function( x )
        -- La variable n de l'àmbit extern està disponible aquí per afegir-la a x
        return x + n
    end
end

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

Es pot declarar una funció per acceptar un nombre variable d'arguments, especificant ... com a element final de la var-list:

function nameoptional ( var-list, ... )
    bloc
end
-- or
function nameoptional ( ... )
    bloc
end

Dins del bloc, es pot utilitzar l'expressió varargs ..., amb el resultat de tots els valors addicionals de la crida de la funció. Per exemple,

local join = function ( separator, ... )
    -- obté els arguments addicionals com una nova taula
    local args = { ... }
    -- obté el recompte d'arguments addicionals, correctament
    local n = select( '#', ... )
    return table.concat( args, separator, 1, n )
end

join( ', ', 'foo', 'bar', 'baz' )
-- retorna la cadena "foo, bar, baz"

La funció select() està dissenyada per treballar amb l'expressió varargs; en particular, s'hauria d'utilitzar select( '#', ... ) en lloc de #{ ... } per comptar el nombre de valors de l'expressió varargs, perquè { ... } pot no ser una seqüència.

Lua ​​proporciona sucre sintàctic per combinar la declaració de funcions i l'assignació a una variable; vegeu Sentències de declaració de funcions per a més detalls.

Tingueu en compte que això no funcionarà:

local factorial = function ( n )
    if n <= 2 then
        return n
    else
        return n * factorial( n - 1 )
    end
end

Com que la declaració de la funció es processa abans que es completi l'assignació de variables locals, "factorial" dins del cos de la funció fa referència a la variable (probablement no definida) d'aquest nom en un àmbit extern. Aquest problema es pot evitar declarant primer la variable local i després assignant-la en una instrucció posterior, o utilitzant la sintaxi d'instrucció de declaració de funció.

Declaracions

Una instrucció és la unitat bàsica d'execució: una assignació, estructura de control, crida de funció, declaració de variable, etc.

Un fragment és una seqüència d'instruccions, opcionalment separades per punts i coma. Un fragment es considera bàsicament el cos d'una funció anònima, de manera que pot declarar variables locals, rebre arguments i retornar valors.

Un bloc també és una seqüència d'instruccions, igual que un fragment. Un bloc es pot delimitar per crear una sola instrucció: do bloc end. Aquests es poden utilitzar per limitar l'abast de les variables locals o per afegir un return o un break al mig d'un altre bloc.

Assignacions

llista-de-variables = llista-d'expressions

La variable-list (llista-de-variables) és una llista de variables separades per comes; la expression-list (llista-d'expressions) és una llista d'una o més expressions separades per comes. Totes les expressions s'avaluen abans de realitzar qualsevol assignació, de manera que a, b = b, a intercanviarà els valors de a i b.

Declaracions de variables locals

local llista-de-variables

local llista-de-variables = llista-d'expressions

Les variables locals es poden declarar a qualsevol lloc dins d'un bloc o fragment. La primera forma, sense una llista d'expressions, declara les variables però no assigna un valor, de manera que totes les variables tenen nil com a valor. La segona forma assigna valors a les variables locals, tal com es descriu anteriorment a Assignacions.

Tingueu en compte que la visibilitat de la variable local comença amb la instrucció després de la declaració de la variable local. Per tant, una declaració com local local x = x declara una variable local x i li assigna el valor de x des de l'àmbit extern. La variable local roman dins de l'àmbit fins al final del bloc més intern que conté la declaració de la variable local.

Estructures de control

while exp do bloc end

La instrucció while repeteix un bloc sempre que una expressió s'avaluï com a true.

repeat bloc until exp

La instrucció repeat repeteix un bloc fins que una expressió s'avaluï com a true. Es pot accedir a les variables locals declarades dins del bloc a l'expressió.

for nom = exp1, exp2, exp3 do bloc end
for nom = exp1, exp2 do bloc end

Aquesta primera forma del bucle for declararà una variable local i repetirà el bloc per a valors de exp1 a exp2 afegint exp3 a cada iteració. Tingueu en compte que exp3 es pot ometre completament, en aquest cas s'utilitza 1, però els valors no numèrics com ara nil i false són un error. Totes les expressions s'avaluen una vegada abans que s'iniciï el bucle.

Aquesta forma del bucle for és aproximadament equivalent a

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

excepte que les variables var, limit i step no siguin accessibles en cap altre lloc. Tingueu en compte que el nom de la variable és local al bloc; per utilitzar el valor després del bucle, s'ha de copiar a una variable declarada fora del bucle.

for var-llista in expressió-llista do bloc end

La segona forma del bucle for funciona amb funcions iteradores. Com en la primera forma, l'expressió-llista només s'avalua una vegada abans de començar el bucle.

Aquesta forma del bucle for és aproximadament equivalent a

do
    local func, static, var = expression-list
    while true do
        local var-list = func( static, var )
        var = var1  -- ''var1'' és la primera variable de ''var-llista''
        if var == nil then
            break
        end
        block
    end
end

excepte que, de nou, les variables func, static i var no siguin accessibles en cap altre lloc. Tingueu en compte que les variables de var-llista són locals al bloc; per utilitzar-les després del bucle, s'han de copiar a variables declarades fora del bucle.

Sovint, la llista-d'expressions és una única crida a funció que retorna els tres valors. Si la funció iteradora es pot escriure de manera que només depengui dels paràmetres que se li passen, això seria el més eficient. Si no, la programació en Lua suggereix que es prefereixi un tancament retornant una taula com a variable estàtica i actualitzar els seus membres a cada iteració.

if exp1 then bloc1 elseif exp2 then bloc2 else bloc3 end

Executa bloc1 si exp1 retorna true, en cas contrari executa bloc2 si exp2 retorna true i bloc3 en cas contrari. La part else block3 es pot ometre i la part elseif exp2 then block2 es pot repetir o ometre segons calgui.

return llista-d'expressions

L'instrucció return s'utilitza per retornar valors d'una funció o d'un fragment (que és només una funció). La llista-d'expressions és una llista de zero o més expressions separades per comes.

Lua ​​implementa recursions: si la llista d'expressions consisteix exactament en una expressió que és una crida de funció, el marc de la pila actual es reutilitzarà per a la crida a aquesta funció. Això té implicacions per a les funcions que tracten la pila de crides, com ara getfenv() i debug.traceback().

La instrucció return ha de ser l'última instrucció del seu bloc. Si per alguna raó es necessita un return al mig d'un bloc, es pot utilitzar un bloc explícit do return end.

break

La instrucció break s'utilitza per finalitzar l'execució d'un bucle while, repeat o for, saltant a la instrucció següent de després del bucle.

La instrucció break ha de ser l'última instrucció del seu bloc. Si per alguna raó es necessita un break al mig d'un bloc, es pot utilitzar un bloc explícit do break end.

A diferència d'altres llenguatges, Lua no té una instrucció "continue" per als bucles (és a dir, una instrucció per passar a la següent iteració sense trencar el bucle del tot). És senzill aconseguir el mateix efecte imbricant un bloc repeat ... until true immediatament dins del bucle principal, que només iterarà una vegada per cada iteració del bucle principal (ja que la seva condició sempre és true). L'ús de break només finalitzarà el bucle intern, cosa que té l'efecte pràctic de fer que el bucle principal continuï a la següent iteració. Si cal utilitzar break al bucle principal, simplement declareu una variable que es comprovi cada vegada que es completa el bucle intern i definiu-la quan calgui.

Crides de funcions com a sentències

Una crida de funció es pot utilitzar com a sentència; en aquest cas, la funció només es crida pels efectes secundaris que pugui tenir (per exemple, mw.log() registra els valors) i qualsevol valor de retorn es descarta.

Sentències de declaració de funcions

Lua ​​proporciona sucre sintàctic per fer que la declaració d'una funció i l'assignació a una variable siguin més naturals. Els següents parells de declaracions són equivalents

-- Declaració bàsica
function func( var-list ) bloc end
func = function ( var-list ) bloc end

-- Funció local
local function func( var-list ) bloc end
local func; func = function ( var-list ) bloc end

-- Funció com a camp en una taula
function table.func( var-list ) bloc end
table.func = function ( var-list ) bloc end

-- Funció com a mètode en una taula
function table:func( var-list ) bloc end
table.func = function ( self, var-list ) bloc end

Tingueu en compte que la notació de dos punts aquí és paral·lela a la notació de dos punts per a crides de funcions, afegint un argument implícit anomenat self al principi de la llista d'arguments.

Gestió d'errors

Es poden "generar" errors mitjançant les funcions error() i assert(). Per "detectar" errors, utilitzeu pcall() o xpcall(). Tingueu en compte que certs errors interns de Scribunto no es poden detectar al codi Lua.

Gestió de memòria

Lua ​​realitza una gestió automàtica de la memòria. Això significa que no us heu de preocupar ni d'assignar memòria per a objectes nous ni d'alliberar-la quan els objectes ja no siguin necessaris. Lua gestiona la memòria automàticament executant un recollidor d'escombraries de tant en tant per recollir tots els objectes morts (és a dir, objectes que ja no són accessibles des de Lua) i objectes que només són accessibles mitjançant referències febles. Tota la memòria utilitzada per Lua està subjecta a una gestió automàtica: taules, funcions, cadenes, etc.

L'alliberament de memòria es fa automàticament i no es pot configurar des de Scribunto.

Biblioteques estàndard

Les biblioteques estàndard de Lua proporcionen serveis essencials i funcions crítiques per al rendiment a Lua. Només es documenten aquí les parts de les biblioteques estàndard que estan disponibles a Scribunto.

Funcions bàsiques

_G

Aquesta variable conté una referència a la taula de variables globals actual; també es pot accedir a la variable global foo com a _G.foo. Cal tenir en compte, però, que no hi ha res d'especial sobre _G en si mateixa; es pot reassignar de la mateixa manera que qualsevol altra variable:

foo = 1
mw.log( foo ) -- registra "1"
_G.foo = 2
mw.log( foo ) -- registra "2"
_G = {}       -- _G ja no apunta a la taula de variables globals
_G.foo = 3
mw.log( foo ) -- encara registra "2"

La taula de variables globals es pot utilitzar com qualsevol altra taula. Per exemple,

-- Crida una funció el nom de la qual s'emmagatzema en una variable
_G[var]()

-- Registra els noms i els valors de cadena de totes les variables globals
for k, v in pairs( _G ) do
   mw.log( k, v )
end

-- Registra la creació de noves variables globals
setmetatable( _G, {
    __newindex = function ( t, k, v )
         mw.log( "Creation of new global variable '" .. k .. "'" )
         rawset( t, k, v )
    end
} )

_VERSION

Una cadena que conté la versió en execució de Lua, p. ex. "Lua 5.1".

assert

assert( v, message, ... )

Si v és nil o false, emet un error. En aquest cas, message s'utilitza com a text de l'error: si és nil (o no especificat), el text és "assertion failed!"; si és una cadena o un número, el text és aquell valor; en cas contrari, assert generarà un error.

Si v és qualsevol altre valor, assert retorna tots els arguments, inclosos v i message.

Una expressió força comuna a Lua és que una funció retorni un valor "true" en funcionament normal i, en cas d'error, retorni nil o false com a primer valor i un missatge d'error com a segon valor. La comprovació fàcil d'errors es pot implementar embolcallant la crida en una crida a assert:

-- Això no comprova els errors
local result1, result2, etc = func( ... )

-- Això funciona igual, però comprova els errors
local result1, result2, etc = assert( func( ... ) )

error

error( message, level )

Emet un error, amb text message.

error normalment afegeix informació sobre la ubicació de l'error. Si level és 1 o s'ha omès, aquesta informació és la ubicació de la crida a l'error en si; 2 utilitza la ubicació de la crida de la funció que ha cridat l'error; i així successivament. Si es passa un 0, s'omet la inclusió de la informació de la ubicació.

getfenv

getfenv( f )

Tingueu en compte que aquesta funció pot no estar disponible, depenent d'allowEnvFuncs en la configuració del motor.

Retorna un entorn (taula de variables globals), tal com s'especifica per f:

• Si 1, nil o s'ha omès, retorna l'entorn de la funció que crida getfenv. Sovint això serà el mateix que _G.
• Els enters del 2 al 10 retornen l'entorn de les funcions superiors de la pila de crides. Per exemple, 2 retorna l'entorn de la funció que ha cridat la funció actual, 3 retorna l'entorn de la funció que crida aquesta funció, i així successivament. Es generarà un error si el valor és superior al nombre de crides de funcions a la pila o si el nivell de la pila de destinació ha retornat amb una crida final.
• Passar una funció retorna l'entorn que s'utilitzarà quan es cridi aquesta funció.

Els entorns utilitzats per totes les funcions de la biblioteca estàndard i per les funcions de la biblioteca de Scribunto estan protegits. Si intenteu accedir a aquests entorns mitjançant getfenv, retornarà zero.

getmetatable

getmetatable( table )

Retorna la metataula d'una taula. Qualsevol altre tipus retornarà nil.

Si la metataula té un camp __metatable, es retornarà aquest valor en lloc de la metataula real.

ipairs

ipairs( t )

Retorna tres valors: una funció iteradora, la taula t i 0. Això està pensat per al seu ús en la forma iteradora de for:

for i, v in ipairs( t ) do
    -- processa cada parell índex-valor
end

Això iterarà sobre els parells ( 1, t[1] ), ( 2, t[2] ), i així successivament, aturant-se quan t[i] sigui nil.

El comportament estàndard es pot anul·lar proporcionant un metamètode __ipairs. Si aquest metamètode existeix, la crida a ipairs retornarà els tres valors retornats per __ipairs( t ) en comptes d'això.

next

next( table, key )

Això permet iterar sobre les claus d'una taula. Si la key és nil o no està especificada, retorna la "primera" clau de la taula i el seu valor; en cas contrari, retorna la clau "següent" i el seu valor. Quan no hi ha més claus disponibles, retorna nil. És possible comprovar si una taula està buida utilitzant l'expressió next( t ) == nil.

Tingueu en compte que l'ordre en què es retornen les claus no està especificat, fins i tot per a taules amb índexs numèrics. Per recórrer una taula en ordre numèric, utilitzeu un for numèric o ipairs.

El comportament no està definit si, quan s'utilitza next per al recorregut, s'assigna un valor a qualsevol clau no existent. Es permet assignar un valor nou (inclòs nil) a un camp existent.

pairs

pairs( t )

Retorna tres valors: una funció iteradora (next o una funció similar), la taula t i nil. Això està pensat per al seu ús en la forma d'iterador de for:

for k, v in pairs( t ) do
    -- processa cada parell clau-valor
end

Això iterarà sobre els parells clau-valor de t igual que ho faria next; vegeu la documentació de next per a les restriccions sobre la modificació de la taula durant el recorregut.

El comportament estàndard es pot anul·lar proporcionant un metamètode __pairs. Si aquest metamètode existeix, la crida a pairs retornarà els tres valors retornats per __pairs( t ) en comptes d'això.

pcall

pcall( f, ... )

Crida la funció f amb els arguments donats en mode protegit. Això significa que si es genera un error durant la crida a f, pcall retornarà false i generarà el missatge d'error. Si no es produeix cap error, pcall retornarà true i tots els valors retornats per la crida.

En pseudocodi, pcall es podria definir d'una manera semblant a aquesta:

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

rawequal

rawequal( a, b )

Això és equivalent a a == b excepte que ignora qualsevol metamètode __eq.

rawget

rawget( table, k )

Això és equivalent a table[k] excepte que ignora qualsevol metamètode __index.

rawset

rawset( table, k, v )

Això és equivalent a table[k] = v excepte que ignora qualsevol metamètode __newindex.

select

select( index, ... )

Si index és un número, retorna tots els arguments de ... a partir d'aquest índex. Si index és la cadena "#", retorna el nombre d'arguments de ....

Nota: a diferència de les taules, les llistes d'arguments (inclosa l'expressió vararg ...) tracten nil com un valor diferent (vegeu la documentació de # i unpack per al problema amb nil a les taules). Per exemple:

• select(2, "foo", "bar") → "bar"
• select(2, "foo", nil, "bar", nil) → nil, "bar", nil
• select("#", "foo", "bar") → 2
• select("#", "foo", "bar", nil) → 3

En altres paraules, select és aproximadament semblant al següent (excepte que també gestiona qualsevol argument nil després de l'argument final diferent de nil):

function select( index, ... )
    local t = { ... }
    local maxindex = table.maxn( t )
    if index == "#" then
        return maxindex
    else
        return unpack( t, index, maxindex )
    end
end

setmetatable

setmetatable( table, metatable )

Defineix la metataula d'una taula. La metatable pot ser nil, però s'ha de proporcionar explícitament.

Si la metataula actual té un camp __metatable, setmetatable generarà un error.

Returns table.

tonumber

tonumber( value, base )

Intenta convertir value a un número. Si ja és un número o una cadena convertible a un número, tonumber retorna aquest número; en cas contrari, retorna nil.

La base opcional (per defecte 10) especifica la base per interpretar el numeral. La base pot ser qualsevol enter entre 2 i 36, ambdós inclosos. En bases superiors a 10, la lletra 'A' (en majúscula o minúscula) representa 10, 'B' representa 11, i així successivament, amb 'Z' es representa el 35.

En base 10, el valor pot tenir una part decimal, estar expressat en notació E i pot tenir un "0x" inicial per indicar la base 16. En altres bases, només s'accepten nombres enters sense signe.

tostring

tostring( value )

Converteix un value en una cadena. Vegeu els tipus de dades anteriors per obtenir més informació sobre com es converteix cada tipus.

El comportament estàndard de les taules es pot anul·lar proporcionant un metamètode __tostring. Si aquest metamètode existeix, la crida a tostring retornarà el valor únic retornat per __tostring( value ) en comptes d'això.

type

type( value )

Retorna el tipus de value com a cadena: "nil", "number", "string", "boolean", "table" o "function".

unpack

unpack( table, i, j )

Retorna valors de la taula donada, com ara table[i], table[i+1], ···, table[j] si s'escrigués manualment. Si és nil o no se li ha assignat un valor, i té per defecte 1 i j té per defecte #table.

Si la taula no té un valor per a una clau en particular, unpack retornarà nil per a aquest valor. Per exemple, unpack({"foo", [3] = "bar"}, 1, 4) retorna "foo", nil, "bar", nil.

Tingueu en compte que els resultats no són deterministes si table no és una seqüència i j és nil o no està especificat; vegeu l'operador Length per a més detalls.

xpcall

xpcall( f, errhandler )

Això és molt semblant a pcall, excepte que el missatge d'error es passa a la funció errhandler abans de ser retornat. Tanmateix, a diferència de pcall, no es poden donar arguments a f.

En pseudocodi, xpcall es podria definir d'una manera semblant a aquesta:

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

Biblioteca de depuració

debug.traceback

debug.traceback( missatge, nivell )

Retorna una cadena amb un rastreig de la pila de crides. S'afegeix una cadena de missatge opcional al principi del rastreig. Un número de nivell opcional indica en quin nivell de la pila s'inicia el rastreig.

Biblioteca matemàtica

math.abs

math.abs( x )

Torna el valor absolut de x.

math.acos

math.acos( x )

Retorna l'arc cosinus de x (donat en radians).

math.asin

math.asin( x )

Retorna l'arc sinus de x (donat en radians).

math.atan

math.atan( x )

Retorna l'arc tangent de x (donat en radians).

math.atan2

math.atan2( y, x )

Retorna l'arc tangent de y/x (donat en radians), utilitzant els signes d'ambdós paràmetres per trobar el quadrant del resultat.

math.ceil

math.ceil( x )

Retorna l'enter més petit major o igual a x.

math.cos

math.cos( x )

Retorna el cosinus de x (donat en radians).

math.cosh

math.cosh( x )

Retorna el cosinus hiperbòlic de x.

math.deg

math.deg( x )

Retorna l'angle x (donat en radians) en graus.

math.exp

math.exp( x )

Retorna el valor $e^x$.

math.floor

math.floor( x )

Retorna l'enter més gran menor o igual a x.

math.fmod

math.fmod( x, y )

Retorna el residu de la divisió d'x per y que arrodoneix el quocient cap a zero. Per exemple, math.fmod( 10, 3 ) dona 1.

math.frexp

math.frexp( x )

Retorna dos valors m i e de manera que:

• Si x és finit i no-zero: $x=m\times 2^e$, e és un enter, i el valor absolut de m és a l'interval $[0.5,1)$
• Si x és zero: m i e són 0
• Si x és NaN o infinit: m és x i e no s'ha especificat

math.huge

El valor que representa l'infinit positiu; més gran o igual que qualsevol altre valor numèric.

math.ldexp

math.ldexp( m, e )

Retorns $m\times 2^e$ (e hauria de ser un enter).

math.log

math.log( x )

Retorna el logaritme natural de x.

math.log10

math.log10( x )

Retorna el logaritme en base 10 de x.

math.max

math.max( x, ... )

Retorna el valor màxim entre els seus arguments.

No s'ha especificat el comportament amb NaN. Amb la implementació actual, es retornarà NaN si x és NaN, però qualsevol altre NaN serà ignorat.

math.min

math.min( x, ... )

Retorna el valor mínim entre els seus arguments.

No s'ha especificat el comportament amb NaN. Amb la implementació actual, es retornarà NaN si x és NaN, però qualsevol altre NaN serà ignorat.

math.modf

math.modf( x )

Retorna dos números, la part integral de x i la part fraccionària de x. Per exemple, math.modf( 1.25 ) dona 1, 0.25.

math.pi

El valor de $\pi$.

math.pow

math.pow( x, y )

Equivalent a x^y.

math.rad

math.rad( x )

Retorna l'angle x (donat en graus) en radians.

math.random

math.random( m, n )

Retorna un número pseudoaleatori.

Els arguments m i n es poden ometre, però si s'especifiquen, s'han de poder convertir en nombres enters.

• Sense arguments, retorna un número real en el rang $[0,1)$
• Amb un argument, retorna un número enter en el rang $[1,m]$
• Amb dos arguments, retorna un número enter en el rang $[m,n]$

Tingueu en compte que es pot produir una sortida incorrecta si m o n són menors que −2147483648 o majors que 2147483647, o si n - m és major que 2147483646.

math.randomseed

math.randomseed( x )

Defineix x com a llavor per al generador pseudoaleatori.

Tingueu en compte que l'ús de la mateixa llavor farà que math.random generi la mateixa seqüència de números.

math.randomseed( tonumber( mw.getLanguage( "en" ):formatDate( "U" ) ) * 10000 + os.clock() * 10000 )

math.sin

math.sin( x )

Retorna el sinus de x (donat en radians).

math.sinh

math.sinh( x )

Retorna el sinus hiperbòlic de x.

math.sqrt

math.sqrt( x )

Retorna l'arrel quadrada de x. Equivalent a x^0.5.

math.tan

math.tan( x )

Retorna la tangent de x (donada en radians).

math.tanh

math.tanh( x )

Retorna la tangent hiperbòlica de x.

Biblioteca del sistema operatiu

os.clock

os.clock()

Retorna una aproximació de la quantitat en segons de temps de CPU utilitzada pel programa.

os.date

os.date( format, time )

El formatDate de la biblioteca d'idiomes es pot utilitzar per a donar un format de data més comprensible

Retorna una cadena o una taula que conté la data i l'hora, formatades segons format. Si el format s'omet o és nil, s'utilitza "%c".

Si es proporciona time, és el la data i hora que s'ha de formatar (vegeu os.time()). En cas contrari, s'utilitza la data i hora actuals.

Si format comença amb '!', la data es formata en UTC en lloc de la data i hora locals del servidor. Després d'aquest caràcter opcional, si el format és la cadena "*t", date retorna una taula amb els camps següents:

• year (complet)
• month (1–12)
• day (1–31)
• hour (0–23)
• min (0–59)
• sec (0–60, per permetre segons intercalars)
• wday (dia laborable, diumenge és 1)
• yday (dia de l'any)
• isdst (indicador d'horari d'estiu, un booleà; pot estar absent si la informació no està disponible)

Si el format no és "*t", date retorna la data i hora com a cadena, formatada segons les mateixes regles que la funció strftime de C.

os.difftime

os.difftime( t2, t1 )

Retorna el nombre de segons de t1 a t2.

os.time

os.time( table )

Retorna un nombre que representa l'hora Unix actual.

Quan es crida sense arguments, retorna la data i hora actuals. Si es passa una taula, s'analitzarà la data i hora codificades a la taula. La taula ha de tenir els camps "year", "month" i "day", i també pot incloure "hour" (per defecte 12), "min" (per defecte 0), "sec" (per defecte 0) i "isdst".

Biblioteca d'empaquetatge

require

require( modulename )

Carrega el mòdul especificat.

Primer, busca a package.loaded[modulename] per veure si el mòdul ja està carregat. Si és així, retorna package.loaded[modulename].

Si no, crida cada carregador de la seqüència package.loaders per intentar trobar un carregador per al mòdul. Si es troba un carregador, es crida aquest carregador. El valor retornat pel carregador s'emmagatzema a package.loaded[modulename] i es retorna.

Consulteu la documentació de package.loaders per obtenir informació sobre els carregadors disponibles.

Per exemple, si teniu un mòdul "Module:Giving" que conté el següent:

local p = {}

p.someDataValue = 'Hola!'

return p

Podeu carregar això en un altre mòdul amb codi com aquest:

local giving = require( "Module:Giving" )

local value = giving.someDataValue -- el valor ara és 'Hola!'

package.loaded

Aquesta taula conté els mòduls carregats. Les claus són els noms dels mòduls i els valors són els valors retornats quan es va carregar el mòdul.

package.loaders

Aquesta taula conté la seqüència de funcions de cerca que s'han d'utilitzar quan es carreguen mòduls. Cada funció del cercador es crida amb un sol argument, el nom del mòdul a carregar. Si es troba el mòdul, el cercador ha de retornar una funció que realment carregarà el mòdul i retornarà el valor que retornarà require. En cas contrari, ha de tornar nil.

Scribunto ofereix dos cercadors:

1. Vegeu a package.preload[modulename] la funció de càrrega
2. Vegeu als mòduls proporcionats amb Scribunto el nom del mòdul i, si això falla, busqueu a l'espai de noms Mòdul:. S'ha de proporcionar el prefix "Mòdul:".

Tingueu en compte que els carregadors Lua estàndard no estan inclosos.

package.preload

Aquesta taula conté funcions de càrrega, utilitzades pel primer cercador que Scribunto inclou a package.loaders.

package.seeall

package.seeall( table )

Estableix el metamètode __index per table a _G.

Biblioteca de cadenes

En totes les funcions de cadena, el primer caràcter es troba a la posició 1, no a la posició 0 com en C, PHP i JavaScript. Els índexs poden ser negatius, en aquest cas compten des del final de la cadena: la posició -1 és l'últim caràcter de la cadena, -2 és el penúltim, i així successivament.

Avís: La biblioteca de cadenes assumeix codificacions de caràcters d'un byte. No pot gestionar caràcters Unicode. Per operar amb cadenes Unicode, utilitzeu els mètodes corresponents de la biblioteca Ustring de Scribunto.

string.byte

string.byte( s, i, j )

Si la cadena es considera com una matriu de bytes, retorna els valors de bytes per a s[i], s[i+1], ···, s[j]. El valor per defecte per a i és 1; el valor per defecte per a j és i. Idèntic a mw.ustring.byte().

string.char

string.char( ... )

Rep zero o més enters. Retorna una cadena amb una longitud igual al nombre d'arguments, en què cada caràcter té el valor de byte igual al seu argument corresponent.

local value = string.char( 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21 ) --''value'' ara és 'Hola!'

Vegeu mw.ustring.char() per a una funció similar que utilitza punts de codi Unicode en lloc de valors de bytes.

string.find

string.find( s, pattern, init, plain )

Busca la primera coincidència de pattern a la cadena s. Si troba una coincidència, find retorna els òfsets a s on comença i acaba aquesta ocurrència; en cas contrari, retorna nil. Si el patró té captures, en una coincidència reeixida els valors capturats també es retornen després dels dos índexs.

Un tercer argument numèric opcional init especifica on començar la cerca; el seu valor per defecte ésnbsp;1 i pot ser negatiu. Un valor true com a quart argument opcional plain desactiva les funcions de coincidència de patrons, de manera que la funció fa una operació de "cerca de subcadena" simple, sense que cap caràcter del pattern es consideri "màgic".

Tingueu en compte que si es dona plain, també s'ha de donar init.

Vegeu mw.ustring.find() per a una funció similar estesa com la descrita als patrons Ustring i on l'òfset d'init és en caràcters en lloc de bytes.

string.format

string.format( formatstring, ... )

Retorna una versió formatada del seu nombre variable d'arguments després de la descripció donada al seu primer argument (que ha de ser una cadena).

La cadena de format utilitza un subconjunt limitat dels especificadors de format printf:

• Els indicadors reconeguts són '-', '+', ' ', '#' i '0'.
• S'admeten amplades de camp enter de fins a 99. '*' no s'admet.
• S'admeten precisions enteres de fins a 99. '*' no s'admet.
• No s'admeten modificadors de longitud.
• Els especificadors de conversió reconeguts són 'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%' i la 'q' no estàndard.
• Els especificadors posicionals (per exemple, "%2$s") no són compatibles.

L'especificador de conversió q és com s, però formata la cadena en un format adequat perquè l'intèrpret Lua la pugui llegir de manera segura: la cadena s'escriu entre cometes dobles i totes les cometes dobles, els salts de línia, els zeros incrustats i les barres invertides de la cadena s'escapen correctament quan s'escriuen.

La conversió entre cadenes i números es realitza tal com s'especifica a Tipus de dades; altres tipus no es converteixen automàticament en cadenes. Les cadenes que contenen caràcters NUL (valor de byte 0) no es gestionen correctament.

Idèntic a mw.ustring.format().

string.gmatch

string.gmatch( s, pattern )

Retorna una funció iteradora que, cada vegada que es crida, retorna les següents captures del pattern sobre la cadena s. Si el pattern no especifica cap captura, es produeix tota la coincidència a cada crida.

Per a aquesta funció, un '^' al principi d'un pattern no és màgic, ja que això impediria la iteració. Es tracta com un caràcter literal.

Vegeu mw.ustring.gmatch() per a una funció similar per a la qual el pattern s'estén com es descriu a Ustring patterns.

string.gsub

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

Retorna dos valors:

1. Una còpia de s en què totes (o les primeres n, si es donen) aparicions del pattern s'han substituït per una cadena de substitució especificada per repl, que pot ser una cadena, una taula o una funció.
2. El nombre total de coincidències que s'han produït.

Si repl és una cadena o un número, el seu valor s'utilitza per a la substitució. El caràcter % funciona com a caràcter d'escapament: qualsevol seqüència de repl de la forma %d, amb d entre 1 i 9, representa el valor de la subcadena capturada d-èssima. La seqüència %0 representa la coincidència completa i la seqüència %% representa un únic %.

Si repl és una taula, es consulta la taula per a cada coincidència, utilitzant la primera captura com a clau; si el pattern no especifica cap captura, s'utilitza tota la coincidència com a clau.

Si repl és una funció, aquesta funció es crida cada vegada que es produeix una coincidència, amb totes les subcadenes capturades passades com a arguments, en ordre; si el pattern no especifica cap captura, s'utilitza tota la coincidència com a únic argument.

Si el valor retornat per la consulta de taula o per la crida de funció és una cadena o un número, s'utilitza com a cadena de reemplaçament; en cas contrari, si és false o nil, no hi ha reemplaçament (és a dir, la coincidència original es conserva a la cadena).

Vegeu mw.ustring.gsub() per a una funció similar en què el patró s'estén tal com es descriu a Patrons Ustring.

string.len

string.len( s )

Retorna la longitud de la cadena, en bytes. No es confon amb caràcters ASCII NUL. Equivalent a #s

Vegeu mw.ustring.len() per a una funció similar que utilitza punts de codi Unicode en lloc de bytes.

string.lower

string.lower( s )

Retorna una còpia d'aquesta cadena amb totes les lletres majúscules ASCII canviades a minúscules. Tots els altres caràcters es deixen sense canvis.

Vegeu mw.ustring.lower() per a una funció similar en què es converteixen tots els caràcters amb definicions de majúscules a minúscules en Unicode.

string.match

string.match( s, pattern, init )

Busca la primera coincidència de pattern a la cadena. Si en troba una, match retorna les captures del pattern; en cas contrari, retorna nil. Si pattern no especifica cap captura, es retorna tota la coincidència.

Un tercer argument numèric opcional, init, especifica on començar la cerca; el seu valor per defecte és 1 i pot ser negatiu.

Vegeu mw.ustring.match() per a una funció similar en què el pattern s'estén com es descriu a Patrons Ustring i l'òfset init és en caràcters en lloc de bytes.

string.rep

string.rep( s, n )

Retorna una cadena que és la concatenació de n còpies de la cadena s. Idèntic a mw.ustring.rep().

string.reverse

string.reverse( s )

Retorna una cadena que és la cadena s invertida (byte a byte).

string.sub

string.sub( s, i, j )

Retorna la subcadena de s que comença a i i continua fins a j; i i j poden ser negatius. Si j és nil o s'omet, continuarà fins al final de la cadena.

En particular, la crida string.sub(s,1,j) retorna un prefix de s amb longitud j, i string.sub(s, -i) retorna un sufix de s amb longitud i.

Vegeu mw.ustring.sub() per obtenir una funció similar en què els desplaçaments són caràcters en lloc de bytes.

string.ulower

string.ulower( s )

Un àlies per a mw.ustring.lower().

string.upper

string.upper( s )

Retorna una còpia d'aquesta cadena amb totes les lletres ASCII minúscules canviades a majúscules. Tots els altres caràcters queden sense canvis.

Vegeu mw.ustring.upper() per obtenir una funció similar en la qual es converteixen tots els caràcters en Unicode de minúscules a majúscules.

string.uupper

string.uupper( s )

Un àlies per mw.ustring.upper().

Patrons

Tingueu en compte que els patrons de Lua són similars a les expressions regulars, però no són idèntics. En particular, tingueu en compte les diferències següents amb les expressions regulars i PCRE:

• El caràcter entre cometes és el percentatge (%), no la barra invertida (\).
• El punt (.) sempre coincideix amb tots els caràcters, incloses les noves línies.
• Mode que no distingeix entre majúscules i minúscules.
• Sense alternança (l'operador |).
• Els quantificadors (*, +, ? i -) només es poden aplicar a caràcters individuals o classes de caràcters, no per capturar grups.
• L'únic quantificador no àvid és -, que és equivalent al quantificador *? de PCRE.
• No hi ha quantificador finit generalitzat (per exemple, el quantificador {n,m} a PCRE).
• Les úniques afirmacions d'amplada zero són ^, $ i el patró "frontera" de %f[set]; afirmacions com ara \b o (?=···) de PCRE no estan presents.
• Els patrons en si no reconeixen escapaments de caràcters com ara \ddd. Tanmateix, com que els patrons són cadenes, aquest tipus d'escapaments es poden utilitzar en els literals de cadena utilitzats per crear la cadena-patró.

Tingueu en compte també que un patró no pot contenir zero bytes incrustats (ASCII NUL, "\0"). Utilitzeu %z en el seu lloc.

Vegeu també Patrons Ustring per a un esquema similar de concordança de patrons amb caràcters Unicode.

Classe de caràcters

Una classe de caràcters s'utilitza per representar un conjunt de caràcters. Es permeten les combinacions següents per descriure una classe de caràcters:

x	(on x no és un dels caràcters màgics ^$()%.[]*+-?) representa el caràcter x mateix.
.	(un punt) Representa qualsevol caràcter.
%a	Representa qualsevol lletra ASCII.
%c	Representa qualsevol caràcter de control ASCII.
%d	Representa qualsevol xifra.
%l	Representa qualsevol lletra ASCII en minúscula.
%p	Representa qualsevol caràcter de puntuació.
%s	Representa qualsevol caràcter ASCII d'espai.
%u	Representa qualsevol caràcter ASCII en majúscula.
%w	Representa qualsevol caràcter ASCII alfanumèric. Tingueu en compte que no inclou el caràcter de subratllat (_), contràriament a la classe habitual \w en les expressions regulars.
%x	Representa qualsevol caràcter dígits hexadecimal.
%z	Representa ASCII NUL, el byte zero.
%A	Qualsevol caràcter que no sigui %a.
%C	Qualsevol caràcter que no sigui %c.
%D	Qualsevol caràcter que no sigui %d.
%L	Qualsevol caràcter que no sigui %l.
%P	Qualsevol caràcter que no sigui %p.
%S	Qualsevol caràcter que no sigui %s.
%U	Qualsevol caràcter que no sigui %u.
%W	Qualsevol caràcter que no sigui %w.
%X	Qualsevol caràcter que no sigui %x.
%Z	Qualsevol caràcter que no sigui %z.
%y	(on y és qualsevol caràcter no alfanumèric) representa el caràcter y. Aquesta és la forma estàndard d'escapar dels caràcters màgics. Qualsevol caràcter de puntuació (fins i tot el que no és màgic) pot anar precedit d'un '%' quan s'utilitza per representar-se en un patró.
[set]	Representa la classe que és la unió de tots els caràcters de set. Es pot especificar un rang de caràcters separant els caràcters finals de l'interval amb un '-'. Totes les classes %y descrites anteriorment també es poden utilitzar com a components a set. Tots els altres caràcters de set es representen a ells mateixos. Per exemple, [%w_] (o [_%w]) representa tots els caràcters alfanumèrics més el guió baix, i [0-7] representa els dígits octals. Per incloure el '-' literal al conjunt, utilitzeu '%-', de manera que [0-7%l%-] representa els dígits octals més les lletres minúscules més el caràcter '-'. La interacció entre rangs i classes no està definida. Per tant, patrons com [%a-z] o [a-%%] no tenen cap significat.
[^set]	Representa el complement de set, on set s'interpreta com anteriorment.

Elements de patró

Un element de patró pot ser

• una sola classe de caràcters, que coincideix amb qualsevol caràcter únic de la classe;
• una sola classe de caràcters seguida de '*', que coincideix amb 0 o més repeticions de caràcters de la classe. Aquests elements de repetició sempre coincidiran amb la seqüència més llarga possible;
• una sola classe de caràcters seguida de '+', que coincideix amb 1 o més repeticions de caràcters de la classe. Aquests elements de repetició sempre coincidiran amb la seqüència més llarga possible;
• una sola classe de caràcters seguida de '-', que també coincideix amb 0 o més repeticions de caràcters de la classe. A diferència de '*', aquests elements de repetició sempre coincidiran amb la seqüència més curta possible
• una sola classe de caràcters seguida de '?', que coincideix amb 0 o 1 ocurrències d'un caràcter a la classe;
• %n, per n entre 1 i 9; aquest element coincideix amb una subcadena igual a la n-ena cadena capturada (vegeu més avall);
• %bxy, on x i y són dos caràcters diferents; aquest element coincideix amb cadenes que comencen per x, acaben amb y i on els x i y estan equilibrats. Això vol dir que, si es llegeix la cadena d'esquerra a dreta, comptant +1 per a un x i -1 per a un y, el final y és el primer y on el recompte arriba a 0. Per exemple, l'element %b() coincideix amb expressions amb parèntesis equilibrats.
• %f[set], un patró de frontera; aquest element coincideix amb una cadena buida en qualsevol posició de manera que el caràcter següent pertany a set i el caràcter anterior no pertany a set. El conjunt set s'interpreta com s'ha descrit anteriorment. El principi i el final del subjecte es tracten com si fossin el caràcter '\0'.
  Tingueu en compte que els patrons de frontera estaven presents però no documentats a Lua 5.1 i s'han afegit oficialment a Lua 5.2. La implementació a Lua 5.2.1 no ha canviat respecte a la 5.1.0.

Patró

Un patró és una seqüència d'elements de patró.

Un ^ al començament d'un patró fixa la coincidència al començament de la cadena subjecte. Un $ al final d'un patró fixa la coincidència al final de la cadena subjecta. En altres posicions, ^ i $ no tenen cap significat especial i es representen a si mateixos.

Captures

Un patró pot contenir sub-patrons tancats entre parèntesis; descriuen captures. Quan una coincidència té èxit, les subcadenes de la cadena subjecta que coincideixen amb les captures s'emmagatzemen ("capturades") per a un ús futur. Les captures estan numerades segons els seus parèntesis esquerres. Per exemple, al patró (a*(.)%w(%s*)), la part de la cadena que coincideix amb a*(.)%w(%s*) s'emmagatzema com a primera captura (i, per tant, té el número 1); el caràcter que coincideix . es captura amb el número 2, i la part que coincideix %s* té el número 3.

Les referències de captura poden aparèixer a la mateixa cadena de patró i fer referència al text que es va capturar anteriorment a la coincidència. Per exemple, ([a-z])%1 coincidirà amb qualsevol parell de lletres minúscules idèntiques, mentre que ([a-z])([a-z])([a-z])[a-z]%3%2%1 coincidirà amb qualsevol palíndrom de 7 lletres.

Com a cas especial, la captura buida () captura la posició actual de la cadena (un número). Per exemple, si apliquem el patró "()aa()" a la cadena "flaaap", hi haurà dues captures: 3 i 5.

Limitacions conegudes: a diferència dels Patrons de biblioteca d'Ustring, els patrons de biblioteca de String no poden contenir més de 32 captures. Si el patró en té més, la funció String generarà un error. Com que la biblioteca Ustring té el seu propi màxim de 10.000 bytes per a patrons (a diferència de la biblioteca String), per tant, és impossible utilitzar un patró que superi ambdós límits, ja que serà incompatible amb ambdues biblioteques.

Biblioteca de taules

La majoria de les funcions de la biblioteca de taules assumeixen que la taula representa una seqüència.

Les funcions table.foreach(), table.foreachi() i table.getn() poden estar disponibles, però estan obsoletes; utilitzeu un bucle for amb pairs(), un bucle for amb ipairs() o l'operador de longitud #, respectivament. Tanmateix, la funció table.setn() està completament obsoleta i generarà un error si s'utilitza.

table.concat

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

Donada una matriu on tots els elements són cadenes o números, retorna table[i] .. sep .. table[i+1] ··· sep .. table[j].

El valor per defecte de sep és una cadena buida, el valor per defecte de i és 1 i el valor per defecte de j és la longitud de la taula. Si i és més gran que j, retorna una cadena buida.

table.insert

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

Insereix l'element value a la posició pos de table, desplaçant altres elements cap amunt a l'espai obert, si cal. El valor per defecte de pos és la longitud de la taula més 1, de manera que una crida table.insert(t, x) insereix x al final de la taula t.

Els elements fins a #table es desplacen; vegeu l'operador de longitud per a les advertències si la taula no és una seqüència.

Nota: quan utilitzeu el paràmetre pos, value no hauria de ser nil. Si intenteu inserir un valor explícit de nil al mig d'una taula, es produirà un comportament no definit, que pot suprimir elements de la taula de manera imprevisible.

table.maxn

table.maxn( table )

Retorna l'índex numèric positiu més gran de la taula donada, o zero si la taula no té índexs numèrics positius.

Per fer-ho, itera per tota la taula. Això és aproximadament equivalent a

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 )

Elimina de table l'element a la posició pos, desplaçant cap avall els altres elements per tancar l'espai, si cal. Retorna el valor de l'element eliminat. El valor per defecte de pos és la longitud de la taula, de manera que una crida table.remove( t ) elimina l'últim element de la taula t.

Els elements fins a #table es desplacen; vegeu operador de longitud per a les advertències si la taula no és una seqüència.

table.sort

table.sort( table, comp )

Ordena els elements de la taula en un ordre determinat, al lloc, d'table[1] a table[#table]. Si es dona comp, aleshores ha de ser una funció que rebi dos elements de taula i retorni true quan el primer sigui menor que el segon (de manera que not comp(a[i+1],a[i]) serà cert després de l'ordenació). Si no es dóna comp, s'utilitza l'operador Lua estàndard <. L'algorisme d'ordenació no és estable; és a dir, els elements considerats iguals per l'ordre donat poden tenir les seves posicions relatives canviades per l'ordenació.

Biblioteques de Scribunto

Totes les biblioteques de Scribunto es troben a la taula mw.

Funcions bàsiques

mw.addWarning

mw.addWarning( text )

Afegeix un avís que es mostra a sobre de la vista prèvia quan es previsualitza una edició. text s'analitza com a wikitext.

mw.allToString

mw.allToString( ... )

Crida a tostring() a tots els arguments i després els concatena amb tabulacions com a separadors.

mw.clone

mw.clone( value )

Crea una còpia profunda d'un valor. Totes les taules (i les seves metataules) es reconstrueixen des de zero. No obstant això, les funcions encara es comparteixen.

mw.getCurrentFrame

mw.getCurrentFrame()

Retorna l'objecte frame actual, normalment l'objecte frame del #invoke més recent.

mw.incrementExpensiveFunctionCount

mw.incrementExpensiveFunctionCount()

Afegeix un al recompte de la "funció d'analitzador costosa" i llança una excepció si supera el límit (vegeu $wgExpensiveParserFunctionLimit ).

mw.isSubsting

mw.isSubsting()

Retorna true si el #invoke actual s'està substituint, false en cas contrari. Vegeu Text de tornada més amunt per a la discussió sobre les diferències entre substituir i no substituir.

mw.loadData

mw.loadData( module )

De vegades, un mòdul necessita taules grans de dades; per exemple, un mòdul de propòsit general per convertir unitats de mesura pot necessitar una gran taula d'unitats reconegudes i els seus factors de conversió. I de vegades aquests mòduls s'utilitzaran moltes vegades en una pàgina. L'anàlisi de la taula de dades gran per cada {{#invoke:}} pot requerir una quantitat de temps important. Per evitar aquest problema, es proporciona mw.loadData().

mw.loadData funciona com require(), amb les diferències següents:

• El mòdul carregat només s'avalua una vegada per pàgina, en lloc d'una vegada per cada crida {{#invoke:}}.
• El mòdul carregat no es registra en package.loaded.
• El valor retornat del mòdul carregat ha de ser una taula. Altres tipus de dades no són compatibles.
• La taula retornada (i totes les subtaules) només pot contenir booleans, números, cadenes i altres taules. No es permeten altres tipus de dades, especialment les funcions.
• És possible que la taula retornada (i totes les subtaules) no tinguin una metataula.
• Totes les claus de la taula han de ser booleans, números o cadenes.
• La taula realment retornada per mw.loadData() té metamètodes que proporcionen accés de només lectura a la taula retornada pel mòdul. Com que no conté les dades directament, pairs() i ipairs() funcionaran, però altres mètodes, inclòs #value, next(), i les funcions de la biblioteca de taules, no funcionaran correctament.

El mòdul hipotètic de conversió d'unitats esmentat anteriorment podria emmagatzemar el seu codi a "Mòdul:Convert" i les seves dades a "Mòdul:Convert/data", i "Mòdul:Convert" utilitzaria local data = mw.loadData( 'Module:Convert/data' ) per carregar les dades de manera eficient.

mw.loadJsonData

mw.loadJsonData( page )

És el mateix que mw.loadData() anterior, excepte que carrega dades de pàgines JSON en lloc de taules Lua. El contingut JSON ha de ser una matriu o un objecte. Veure també mw.text.jsonDecode(). mw.loadJsonData does not check if the user has 'read' permissions to access the page. It throws an error if the page does not exist or if it is empty. It also increases the expensive parser function count by 1.

mw.dumpObject

mw.dumpObject( object )

Serialitza object en una representació llegible per les persones i després retorna la cadena resultant.

mw.log

mw.log( ... )

Passa els arguments a mw.allToString() i després afegeix la cadena resultant a la memòria intermèdia del registre.

Quan s'invoca un mòdul Scribunto en una pàgina, el buffer del registre s'inclou com a "Registres de Lua" a les dades de perfil de l'Analitzador, que és visible a la part inferior de la pàgina quan es previsualitza. També s'hi pot accedir mitjançant JavaScript com a limitreport-logs, que s'inclou a l'objecte Scribunto a wgPageParseReport a partir de mw.config (és a dir, mw.config.get("wgPageParseReport").scribunto["limitreport-logs"]).

A la consola de depuració, la funció print() és un àlies per a aquesta funció.

mw.logObject

mw.logObject( object )
mw.logObject( object, prefix )

Crida a mw.dumpObject() i afegeix la cadena resultant a la memòria intermèdia del registre. Si es dona prefix, s'afegirà a la memòria intermèdia de registre seguit d'un signe igual abans d'afegir la cadena serialitzada (és a dir, el text registrat serà "prefix = object-string").

Objecte frame

L'objecte frame (marc) és la interfície dels paràmetres passats a {{#invoke:}} i a l'analitzador.

Tingueu en compte que no hi ha cap biblioteca frame i no hi ha cap variable global anomenada frame. Normalment, un objecte frame s'obté passant com a paràmetre a la funció cridada per {{#invoke:}}, i també es pot obtenir a partir de mw.getCurrentFrame().

frame.args

Una taula per accedir als arguments passats al frame. Per exemple, si es crida un mòdul des de wikitext amb

{{#invoke:module|function|arg1|arg2|name=arg3}}

llavors frame.args[1] retornarà "arg1", frame.args[2] retornarà "arg2" i frame.args['name'] (o frame.args.name) retornarà "arg3". També és possible iterar sobre arguments amb pairs( frame.args ) o ipairs( frame.args ). Tanmateix, a causa de com Lua implementa iteradors de taula, iterar sobre arguments els retornarà en un ordre no especificat i no hi ha manera de conèixer l'ordre original tal com apareixen al wikitext.

Tingueu en compte que els valors d'aquesta taula són sempre cadenes; tonumber() es pot utilitzar per convertir-los en números, si cal. Les claus, però, són números encara que s'indiquin explícitament a la invocació: {{#invoke:module|function|1|2=2}} dona valors de cadena "1" i "2" indexats per les tecles numèriques 1 i 2.

Igual que en les invocacions de plantilla de MediaWiki, els arguments amb nom tindran espais en blanc inicials i posteriors eliminats tant del nom com del valor abans de passar-los a Lua, mentre que els arguments sense nom no tindran espais en blanc eliminats.

Per raons de rendiment, frame.args utilitza una metataula, en lloc de contenir directament els arguments. Els valors dels arguments es demanen a MediaWiki sota demanda. Això vol dir que la majoria dels altres mètodes de taula no funcionaran correctament, inclòs #frame.args, next( frame.args ), i les funcions de la Biblioteca de taules.

Si la sintaxi del preprocessador, com ara les invocacions de plantilla i els arguments de tres claus, s'inclouen dins d'un argument a #invoke, no s'expandiran, després de passar-les a Lua, fins que els seus valors es demanin a Lua. Si certes etiquetes especials escrites en notació XML, com ara pre, ‎<nowiki>, ‎<gallery> i ‎<ref>, s'inclouen com a arguments de #invoke" llavors aquestes etiquetes es convertiran a "strip markers": cadenes especials que comencen amb un caràcter d'eliminació (ASCII 127), per ser substituïdes per HTML després de ser retornades des de #invoke.

frame:callParserFunction

• frame:callParserFunction( name, args )
• frame:callParserFunction( name, ... )
• frame:callParserFunction{ name = string, args = table }

Tingueu en compte l'ús de arguments amb nom.

La crida a una funció analitzadora retorna una cadena adequada. Això és preferible a frame:preprocess, però sempre que sigui possible, les funcions natives de Lua o les funcions de biblioteca de Scribunto haurien de ser preferides a aquesta interfície.

Les crides següents són aproximadament equivalents al wikitext indicat:

-- {{ns:0}}
frame:callParserFunction( 'ns', { 0 } )
frame:callParserFunction( 'ns', 0 )
frame:callParserFunction{ name = 'ns', args = { 0 } }

-- {{#tag:nowiki|some text}}
frame:callParserFunction( '#tag', { 'nowiki', 'some text' } )
frame:callParserFunction( '#tag', 'nowiki', 'some text' )
frame:callParserFunction( '#tag:nowiki', 'some text' )
frame:callParserFunction{ name = '#tag', args = { 'nowiki', 'some text' } }

-- {{#tag:ref|some text|name=foo|group=bar}}
frame:callParserFunction( '#tag', { 'ref',
    'some text', name = 'foo', group = 'bar'
} )

Make sure you provide the unnamed parameter after the colon even if it's empty and ignored by the parser function.

frame:callParserFunction( '#someparserfunction', { '', name = 'foo', group = 'bar' } )

Tingueu en compte que, igual que amb frame:expandTemplate(), el nom i els arguments de la funció no es processen prèviament abans de passar a la funció analitzadora.

frame:expandTemplate

frame:expandTemplate{ title = title, args = table }

Tingueu en compte l'ús d'arguments amb nom.

Aquesta és una transclusió. La crida:

frame:expandTemplate{ title = 'template', args = { 'arg1', 'arg2', name = 'arg3' } }

fa aproximadament el mateix des de Lua que {{template|arg1|arg2|name=arg3}} fa al wikitext. Com en la transclusió, si el títol passat no conté un prefix d'espai de noms, se suposarà que es troba a l'espai de noms Plantilla:.

Tingueu en compte que el títol i els arguments no es processen prèviament abans de passar a la plantilla:

-- Això és aproximadament equivalent al wikitext {{template|{{!}}}}
frame:expandTemplate{ title = 'template', args = { '|' } }

-- Això és aproximadament equivalent al wikitext {{template|{{((}}!{{))}}}}
frame:expandTemplate{ title = 'template', args = { '{{!}}' } }

frame:extensionTag

• frame:extensionTag( name, content, args )
• frame:extensionTag{ name = string, content = string, args = table_or_string }

Això és equivalent a una crida a frame:callParserFunction() amb el nom de funció '#tag' (vegeu Ajuda:Paraules màgiques#Miscel·lània) i amb name i content davant de args.

-- Aquests són equivalents
frame:extensionTag( 'ref', 'some text', { name = 'foo', group = 'bar' } )
frame:extensionTag{ name = 'ref', content = 'some text', args = { name = 'foo', group = 'bar' } }
frame:callParserFunction( '#tag', { 'ref' ,
    'some text', name = 'foo', group = 'bar'
} )

-- Aquests són equivalents
frame:extensionTag{ name = 'ref', content = 'some text', args = { 'some other text' } }
frame:callParserFunction( '#tag', { 'ref',
    'some text', 'some other text'
} )

frame:getParent

frame:getParent()

Cridat al frame creat per {{#invoke:}}, retorna el frame de la pàgina que va cridar {{#invoke:}}. Cridat en aquell frame, retorna nil.

Per exemple, si la plantilla {{Example}} conté el codi {{#invoke:ModuleName|FunctionName|A|B}} i una pàgina transclou aquesta plantilla amb el codi {{Example|C|D}}, aleshores a Module:ModuleName, cridant frame.args[1] i frame.args[2] retorna "A" i "B", i cridant frame:getParent().args[1] i frame:getParent().args[2] retorna "C" i "D", amb frame essent el primer argument de la crida de funció.

frame:getTitle

frame:getTitle()

Retorna el títol associat amb el frame com a cadena. Per al frame creat per {{#invoke:}}, aquest és el títol del mòdul invocat.

frame:newChild

frame:newChild{ title = title, args = table }

Tingueu en compte l'ús d'arguments amb nom.

Crea un nou objecte frame que sigui un fill del frame actual, amb arguments i títol opcionals.

Això està pensat principalment per proporcionar un entorn de frame pare específic per a crides com frame:newChild(...):callParserFunction('#invoke', ...) o frame:newChild(...):preprocess(...), etc., per a mòduls que comproven el seu frame pare, etc. Més enllà de la depuració casual, per exemple, provant funcions a la consola de depuració, etc., no s'hauria d'utilitzar per intentar emular {{#invoke:}} en codi de producció, ja que hi ha diverses maneres en què el mòdul cridat pot detectar com es crida. El nombre de frames que es poden crear alhora és limitat.

frame:preprocess

• frame:preprocess( string )
• frame:preprocess{ text = string }

Això expandeix el wikitext en el context del frame, és a dir, les plantilles, les funcions d'anàlisi i els paràmetres com ara $"param1" s'expandeixen i retornen el text expandit. Certes etiquetes especials escrites en notació d'estil XML, com ara ‎<pre>, ‎<nowiki>, ‎<gallery> i ‎<ref>, se substituiran per "marques de fragment" — cadenes especials que comencen amb un caràcter d'eliminació (ASCII 127), que se substituiran per HTML després que es retornin des de #invoke.

Si esteu expandint una sola plantilla, utilitzeu frame:expandTemplate en lloc d'intentar construir una cadena de wikitext per passar a aquest mètode. És més ràpid i menys propens a errors si els arguments contenen caràcters de barra vertical o altres wikimarkups.

Si esteu expandint una sola funció d'ananàlisi, utilitzeu frame:callParserFunction pels mateixos motius.

frame:getArgument

• frame:getArgument( arg )
• frame:getArgument{ name = arg }

Obté un objecte per a l'argument especificat, o nil si no es proporciona l'argument.

L'objecte retornat té un mètode, object:expand(), que retorna el wikitext expandit per a l'argument.

frame:newParserValue

• frame:newParserValue( text )
• frame:newParserValue{ text = text }

Retorna un objecte amb un mètode, object:expand(), que retorna el resultat de frame:preprocess( text ).

frame:newTemplateParserValue

frame:newTemplateParserValue{ title = title, args = table }

Tingueu en compte l'ús d'arguments amb nom.

Retorna un objecte amb un mètode, object:expand(), que retorna el resultat de frame:expandTemplate cridat amb els arguments donats.

frame:argumentPairs

frame:argumentPairs()

Igual que pairs( frame.args ). Inclòs per compatibilitat amb versions anteriors.

Biblioteca hash

mw.hash.hashValue

mw.hash.hashValue( algo, valor )

Hash és obtenir un valor, de tipus cadena, únic i identificatiu, amb un algoritme especificat. Es poden obtenir algoritmes vàlids utilitzant mw.hash.listAlgorithms().

mw.hash.listAlgorithms

mw.hash.listAlgorithms()

Retorna una llista d'algoritmes per a hash compatibles, per al seu ús a mw.hash.hashValue(). This method is a passthrough of hash_algos().

Biblioteca HTML

mw.html és una interfície fluida per crear HTML complex des de Lua. En molts wikis de Wikimedia, això s'implementava anteriorment a Module:HtmlBuilder. Es pot crear un objecte mw.html utilitzant mw.html.create.

Les funcions documentades com a mw.html.name estan disponibles a la taula global mw.html; les funcions documentades com a mw.html:name i html:name són mètodes d'un objecte mw.html (vegeu mw.html.create).

Un exemple bàsic podria ser així:

local div = mw.html.create( 'div' )
div
     :attr( 'id', 'testdiv' )
     :css( 'width', '100%' )
     :wikitext( 'Some text' )
     :tag( 'hr' )
return tostring( div )
-- Output: <div id="testdiv" style="width:100%;">Some text<hr /></div>

mw.html.create

mw.html.create( tagName, args )

Crea un nou objecte mw.html que conté un element html tagName. També podeu passar una cadena buida o nil com a tagName per crear un objecte mw.html buit.

args pot ser una taula amb les claus següents:

• args.selfClosing: Força que l'etiqueta actual es tanqui automàticament, fins i tot si mw.html no la reconeix com a autotancant.
• args.parent: Pare de la instància mw.html actual (pensat per a ús intern).

mw.html:node

html:node( builder )

Afegeix un node fill mw.html (builder) a la instància mw.html actual. Si es passa un paràmetre nil, això no és una opció. Un node (builder) és una representació de cadena d'un element html.

mw.html:wikitext

html:wikitext( ... )

Afegeix un nombre indeterminat de cadenes wikitext a l'objecte mw.html.

Tingueu en compte que això s'atura al primer element nil.

El wikitext bàsic s'analitzarà, com ara HTML, enllaços, negreta, llistes o taules. Tanmateix, les plantilles i les funcions d'anàlisi no s'avaluaran si es passen directament a aquesta funció, tret que provinguin de paràmetres de plantilla. Aquestes es representaran en text pla. Per avaluar-les, s'hauran de passar a través de frame:preprocess.

mw.html:newline

html:newline()

Afegeix un salt de línia a l'objecte mw.html. Útil quan s'utilitza abans i després de mw.html:wikitext(), quan el wikitext conté llistes o taules, la sintaxi de les quals només té un significat especial quan són presents al principi d'una línia.

mw.html:tag

html:tag( tagName, args )

Afegeix un nou node fill amb el tagName donat al constructor i retorna una instància mw.html que representa aquest nou node. El paràmetre args és idèntic al de mw.html.create.

Tingueu en compte que, a diferència d'altres mètodes com ara html:node(), aquest mètode no retorna la instància mw.html actual, sinó la instància mw.html de l'etiqueta recentment inserida. Assegureu-vos d'utilitzar html:done() per anar a la instància mw.html pare, o html:allDone() si teniu etiquetes imbricades en diversos nivells.

mw.html:attr

html:attr( name, value )
html:attr( table )

Definiu un atribut HTML amb els name i value donats al node. Alternativament, es pot passar una taula que contingui parells d'atributs nom->valor per definir. En la primera forma, un valor de nil fa que qualsevol atribut amb el nom donat no estigui definit si ja s'havia definit anteriorment.

mw.html:getAttr

html:getAttr( name )

Obté el valor d'un atribut HTML definit anteriorment amb html:attr() amb el name donat.

mw.html:addClass

html:addClass( class )

Afegeix un nom de classe a l'atribut de classe del node. Si es passa un paràmetre nil, això no és una opció.

mw.html:css

html:css( name, value )
html:css( table )

Definiu una propietat CSS amb els name i value donats al node. Alternativament, es pot passar una taula que contingui parells de nom->valor de propietats per definir. En la primera forma, un valor nil fa que qualsevol propietat amb el nom donat no estigui definida si ja s'havia definit anteriorment.

mw.html:cssText

html:cssText( css )

Afegiu una mica de css en brut a l'atribut d'estil del node. Si es passa un paràmetre nil, això no és una opció.

mw.html:done

html:done()

Retorna el node pare sota el qual es va crear el node actual. Com jQuery.end, aquesta és una funció convenient per permetre construir diversos nodes fills que s'encadenen en una sola instrucció.

mw.html:allDone

html:allDone()

Com html:done(), però recorre tot el camí fins al node arrel de l'arbre i el retorna.

Biblioteca language (d'idiomes)

Els codis d'idioma es descriuen a codi d'idioma. Molts dels codis d'idioma de MediaWiki són similars a les etiquetes d'idioma IETF, però no tots els codis d'idioma de MediaWiki són etiquetes IETF vàlides o viceversa.

Les funcions documentades com a mw.language.name estan disponibles a la taula global mw.language; les funcions documentades com a mw.language:name i lang:name són mètodes d'un objecte d'idioma (vegeu mw.language.new o mw.language.getContentLanguage).

mw.language.fetchLanguageName

mw.language.fetchLanguageName( code, inLanguage )

El nom complet de l'idioma per al codi d'idioma donat: nom natiu (autòmim d'idioma) per defecte, nom traduït a l'idioma de destinació si es dona un valor per a inLanguage.

mw.language.fetchLanguageNames

mw.language.fetchLanguageNames()
mw.language.fetchLanguageNames( inLanguage )
mw.language.fetchLanguageNames( inLanguage, include )

Obté la llista d'idiomes coneguts per MediaWiki, retornant una taula que mapatge el codi d'idioma al nom de l'idioma.

Per defecte, el nom retornat és l'autònim de l'idioma; si es passa un codi d'idioma per a inLanguage, es retornen tots els noms en aquest idioma.

Per defecte, només es retornen els noms d'idiomes coneguts per MediaWiki; si es passa 'all' per a include, es retornaran tots els idiomes disponibles (des de Extension:CLDR ), mentre que si es passa 'mwfile' només s'inclouran els idiomes que tinguin missatges personalitzats inclosos amb el nucli de MediaWiki o extensions habilitades. Per seleccionar explícitament el valor per defecte, es pot passar 'mw'.

mw.language.getContentLanguage

mw.language.getContentLanguage()
mw.getContentLanguage()

Retorna un nou objecte d'idioma per a l'idioma de contingut per defecte del wiki.

mw.language.getFallbacksFor

Cadenes alternatives

mw.language.getFallbacksFor( code )
mw.language.getFallbacksFor( code, mode )

Retorna una llista dels codis d'idioma alternatius de MediaWiki per al codi especificat.

MediaWiki version:

≥ 1.46 Gerrit change 1200597

Opcionalment, podeu passar un dels dos modes alternatius compatibles com a segon argument:

mw.language.FALLBACK_MESSAGES

Inclou l'alternativa implícita final a 'en' (anglès) per a tots els idiomes. Aquest és el comportament per defecte.

mw.language.FALLBACK_STRICT

No inclogueu aquesta alternativa implícita, si no només enumereu les alternatives explícites de l'idioma. (Algunes llengües tenen una alternativa explícita a l'anglès, però la majoria no.)

mw.language.getFallbacksFor( 'hsb' ) -- { 'dsb', 'de', 'en' }
mw.language.getFallbacksFor( 'hsb', mw.language.FALLBACK_MESSAGES ) -- { 'dsb', 'de', 'en' }
mw.language.getFallbacksFor( 'hsb', mw.language.FALLBACK_STRICT ) -- { 'dsb', 'de' }
mw.language.getFallbacksFor( 'en-gb', mw.language.FALLBACK_STRICT ) -- { 'en' }

mw.language.isKnownLanguageTag

mw.language.isKnownLanguageTag( code )

Retorna true si MediaWiki coneix un codi d'idioma.

Un codi d'idioma és "conegut" si és un "codi integrat vàlid" (és a dir, retorna true per a mw.language.isValidBuiltInCode) i retorna una cadena no buida per a mw.language.fetchLanguageName.

mw.language.isSupportedLanguage

mw.language.isSupportedLanguage( code )

Comprova si hi ha alguna localització disponible per a aquest codi d'idioma a MediaWiki.

Un codi d'idioma és "admès" si és un codi "vàlid" (retorna true per a mw.language.isValidCode), no conté majúscules i té un fitxer de missatges a la versió actual de MediaWiki.

És possible que un codi d'idioma sigui "admès" però no "conegut" (és a dir, retorna true per a mw.language.isKnownLanguageTag). També tingueu en compte que certs codis són "admesos" tot i que mw.language.isValidBuiltInCode retorna false.

mw.language.isValidBuiltInCode

mw.language.isValidBuiltInCode( code )

Retorna true si un codi d'idioma té una forma vàlida per a la personalització interna de MediaWiki.

És possible que el codi no correspongui realment a cap idioma conegut.

Un codi d'idioma és un "codi integrat vàlid" si és un codi "vàlid" (és a dir, retorna true per mw.language.isValidCode); consta només de lletres, números i guions ASCII; i té almenys dos caràcters de llargada.

Tingueu en compte que alguns codis són "admesos" (és a dir, retornen true de mw.language.isSupportedLanguage) tot i que aquesta funció retorna false.

mw.language.isValidCode

mw.language.isValidCode( code )

Retorna true si una cadena de codi d'idioma té una forma vàlida, existeixi o no. Això inclou els codis que s'utilitzen únicament per a la personalització a través de l'espai de noms MediaWiki.

És possible que el codi no correspongui realment a cap idioma conegut.

Un codi d'idioma és vàlid si no conté certs caràcters no segurs (dos punts, cometes simples o dobles, barres inclinades, barres inclinades invertides, parèntesis angulars, l'et o l'ASCII NUL) i està permès en un títol de pàgina.

mw.language.new

mw.language.new( code )
mw.getLanguage( code )

Crea un nou objecte d'idioma. Els objectes d'idioma no tenen cap propietat accessible públicament, però tenen diversos mètodes, que es documenten a continuació.

Hi ha un límit de 200 en el nombre de codis d'idioma diferents que es poden utilitzar en una pàgina. Superar aquest límit provocarà errors.

mw.language:getCode

lang:getCode()

Retorna el codi d'idioma per a aquest objecte d'idioma.

mw.language:toBcp47Code

lang:toBcp47Code()

Retorna el codi d'idioma estàndard BCP-47 per a aquest objecte d'idioma (vegeu també Manual:Language/BCP-47 ). Aquesta és la cadena de codi que és adequada per utilitzar en HTML, per exemple com a valor d'un atribut lang.

mw.language:getFallbackLanguages

lang:getFallbackLanguages()
lang:getFallbackLanguages( mode )

Retorna una llista dels codis d'idioma alternatius de MediaWiki per a aquest objecte d'idioma. Equivalent a mw.language.getFallbacksFor( lang:getCode() ) o mw.language.getFallbacksFor( lang:getCode(), mode ).

mw.language:isRTL

lang:isRTL()

Retorna true si l'idioma s'escriu de dreta a esquerra, false si s'escriu d'esquerra a dreta.

mw.language:lc

lang:lc( s )

Converteix la cadena a minúscules, respectant qualsevol regla especial per a l'idioma donat.

Quan es carrega la biblioteca Ustring, la funció mw.ustring.lower() s'implementa com una crida a mw.language.getContentLanguage():lc( s ).

mw.language:lcfirst

lang:lcfirst( s )

Converteix el primer caràcter de la cadena a minúscules, com amb lang:lc().

mw.language:uc

lang:uc( s )

Converteix la cadena a majúscules, respectant qualsevol regla especial per a l'idioma donat.

Quan es carrega la biblioteca Ustring, la funció mw.ustring.upper() s'implementa com una crida a mw.language.getContentLanguage():uc( s ).

mw.language:ucfirst

lang:ucfirst( s )

Converteix el primer caràcter de la cadena a majúscules, com amb lang:uc().

mw.language:caseFold

lang:caseFold( s )

Converteix la cadena a una representació adequada per a la comparació sense distinció entre majúscules i minúscules. Tingueu en compte que el resultat pot no tenir cap sentit quan es mostra.

mw.language:formatNum

lang:formatNum( n )
lang:formatNum( n, options )

Formata un número amb separadors d'agrupació i decimals adequats per a l'idioma donat. Donat 123456.78, això pot produir "123,456.78", "123.456,78" o fins i tot alguna cosa semblant a "١٢٣٬٤٥٦٫٧٨", depenent de l'idioma i la configuració del wiki.

El options és una taula d'opcions, que pot ser:

• noCommafy: Defineix true per ometre els separadors d'agrupació i utilitzar un punt (.) com a separador decimal. La transformació de dígits encara pot ocórrer, que pot incloure la transformació del separador decimal.

mw.language:formatDate

lang:formatDate( format, timestamp, local )

Formata una data segons la cadena de format donada. Si s'omet timestamp, el valor per defecte és l'hora actual. El valor de local ha de ser un booleà o nil; si és true, l'hora es formata en l'hora local del wiki en lloc d'UTC.

La cadena de format i els valors admesos per a timestamp són idèntics als de la funció d'anàlisi #time de Extensió:ParserFunctions . Tingueu en compte, però, que les barres invertides poden haver de ser duplicades en un literal de cadena Lua, ja que Lua també utilitza la barra invertida com a caràcter d'escapament, mentre que wikitext no ho fa:

-- Aquest literal de cadena conté un salt de línia, no els dos caràcters "\n", per la qual cosa no és equivalent a {{#time:\n}}.
lang:formatDate( '\n' )

-- Això és equivalent a {{#time:\n}}, no a {{#time:\\n}}.
lang:formatDate( '\\n' )

-- Això és equivalent a {{#time:\\n}}, no a {{#time:\\\\n}}.
lang:formatDate( '\\\\n' )

mw.language:formatDuration

lang:formatDuration( seconds )
lang:formatDuration( seconds, chosenIntervals )

Divideix una durada en segons en unitats més llegibles per humans, p. ex. 12345 en 3 hores, 25 minuts i 45 segons, retornant el resultat com a cadena.

chosenIntervals, si es dona, és una taula amb valors que anomena les unitats d'interval que s'utilitzaran a la resposta. Aquests inclouen millennia, centuries, decades, years, weeks, days, hours, minutes, seconds.

mw.language:parseFormattedNumber

lang:parseFormattedNumber( s )

Això pren un número formatat per lang:formatNum() i retorna el número real. En altres paraules, bàsicament és una versió de tonumber() que s'adapta a l'idioma.

mw.language:convertPlural

lang:convertPlural( n, ... )
lang:convertPlural( n, forms )
lang:plural( n, ... )
lang:plural( n, forms )

Això tria la forma gramatical adequada entre forms (que ha de ser una taula de seqüència) o ... en funció del número n. Per exemple, en anglès podeu utilitzar n .. ' ' .. lang:plural( n, 'sock', 'socks' ) o n .. ' ' .. lang:plural( n, { 'sock', 'socks' } ) per generar text gramaticalment correcte tant si hi ha 1 sock com 200 socks.

Els valors necessaris per a la seqüència depenen de l'idioma; vegeu localització de paraules màgiques i PF de translatewiki sobre PLURAL per obtenir més informació.

mw.language:convertGrammar

lang:convertGrammar( word, case )
lang:grammar( case, word )

Tingueu en compte l'ordre diferent dels paràmetres entre els dos àlies. convertGrammar coincideix amb l'ordre del mètode del mateix nom a l'objecte Language de MediaWiki, mentre que grammar coincideix amb l'ordre de la funció d'anàlisi del mateix nom, documentada a Ajuda:Paraules màgiques#Localització.

Això tria la forma flexionada adequada de word per al codi d'inflexió case donat.

Els valors possibles per a word i case depenen de l'idioma, vegeu Special:MyLanguage/Help:Magic words#Localisation i translatewiki:Gramàtica per a més detalls.

mw.language:gender

lang:gender( what, masculine, feminine, neutral )
lang:gender( what, { masculine, feminine, neutral } )

Tria la cadena corresponent al gènere de what, que pot ser "masculí", "femení" o un nom d'usuari registrat.

mw.language:getArrow

lang:getArrow( direction )

Retorna un caràcter de fletxa Unicode corresponent a direction:

• forwards: "→" o "←" segons la direccionalitat de l'idioma.
• backwards: "←" o "→" depenent de la direccionalitat de l'idioma.
• left: "←"
• right: "→"
• up: "↑"
• down: "↓"

mw.language:getDir

lang:getDir()

Retorna "ltr" o "rtl", depenent de la direccionalitat de l'idioma.

mw.language:getDirMark

lang:getDirMark( opposite )

Retorna una cadena que conté U+200E (la marca d'esquerra a dreta) o U+200F (la marca de dreta a esquerra), depenent de la direccionalitat de l'idioma i de si opposite és un valor true o false.

mw.language:getDirMarkEntity

lang:getDirMarkEntity( opposite )

Retorna "‎" o "‏", depenent de la direccionalitat de l'idioma i de si opposite és un valor true o false.

mw.language:getDurationIntervals

lang:getDurationIntervals( seconds )
lang:getDurationIntervals( seconds, chosenIntervals )

Divideix una durada en segons en unitats més llegibles per humans, p. ex. 12345 a 3 hores, 25 minuts i 45 segons, retornant el resultat com una taula que assigna noms d'unitats a números.

chosenIntervals, si es proporciona, és una taula amb valors que anomena les unitats d'interval que s'utilitzaran a la resposta. Aquests inclouen millennia, centuries, decades, years, weeks, days, hours, minutes, seconds.

Aquestes paraules clau d'unitats també són les claus que s'utilitzen a la taula de resposta. Només es defineixen unitats amb un valor diferent de zero a la resposta, tret que la resposta sigui buida, en aquest cas es retorna la unitat més petita amb un valor de 0.

Biblioteca message (de missatges)

Aquesta biblioteca és una interfície per als missatges de localització i l'espai de noms MediaWiki:.

Les funcions documentades com a mw.message.name estan disponibles a la taula global mw.message; les funcions documentades com a mw.message:name i msg:name són mètodes d'un objecte de missatge (vegeu mw.message.new).

mw.message.new

mw.message.new( key, ... )

Crea un nou objecte de missatge per al missatge key donat. Els paràmetres restants es passen al mètode params() del nou objecte.

L'objecte de missatge no té propietats, però té diversos mètodes documentats a continuació.

mw.message.newFallbackSequence

mw.message.newFallbackSequence( ... )

Crea un nou objecte de missatge per als missatges donats (s'utilitzarà el primer que existeixi).

L'objecte de missatge no té propietats, però té diversos mètodes documentats a continuació.

mw.message.newRawMessage

mw.message.newRawMessage( msg, ... )

Crea un nou objecte de missatge, utilitzant directament el text donat en lloc de buscar un missatge internacionalitzat. Els paràmetres restants es passen al mètode params() del nou objecte.

L'objecte de missatge no té propietats, però té diversos mètodes documentats a continuació.

mw.message.rawParam

mw.message.rawParam( value )

Ajusta el valor perquè no s'analitzi com a wikitext.

mw.message.numParam

mw.message.numParam( value )

Ajusta el valor perquè es formati automàticament com a lang:formatNum(). Tingueu en compte que això no depèn de la disponibilitat de la biblioteca Language (d'idiomes).

mw.message.getDefaultLanguage

mw.message.getDefaultLanguage()

Retorna un objecte Language per a l'idioma per defecte.

mw.message:params

msg:params( ... )
msg:params( params )

Afegeix paràmetres al missatge, que es poden passar com a arguments individuals o com a taula de seqüència. Els paràmetres han de ser números, cadenes o els valors especials retornats per mw.message.numParam() o mw.message.rawParam(). Si s'utilitza una taula de seqüència, els paràmetres han d'estar directament presents a la taula; les referències que utilitzen __index metamethod no funcionaran.

Retorna l'objecte msg per permetre l'encadenament de crides.

mw.message:rawParams

msg:rawParams( ... )
msg:rawParams( params )

Com :params(), però té l'efecte de passar tots els paràmetres primer a través de mw.message.rawParam().

Retorna l'objecte msg per permetre l'encadenament de crides.

mw.message:numParams

msg:numParams( ... )
msg:numParams( params )

Igual que :params(), però té l'efecte de passar tots els paràmetres primer a través de mw.message.numParam().

Retorna l'objecte msg per permetre l'encadenament de crides.

mw.message:inLanguage

msg:inLanguage( lang )

Especifica l'idioma que s'utilitzarà en processar el missatge. lang pot ser una cadena o una taula amb un mètode getCode() (és a dir, un objecte Language).

L'idioma per defecte és el que retorna mw.message.getDefaultLanguage().

Retorna l'objecte msg per permetre l'encadenament de crides.

mw.message:useDatabase

msg:useDatabase( bool )

Especifica si cal buscar els missatges a l'espai de noms MediaWiki: (és a dir, buscar a la base de dades) o simplement utilitzar els missatges per defecte distribuïts amb MediaWiki.

El valor per defecte és true.

Retorna l'objecte msg per permetre l'encadenament de crides.

mw.message:plain

msg:plain()

Substitueix els paràmetres i retorna el text wiki del missatge tal com és. Les crides de plantilla i les funcions d'anàlisi estan intactes.

mw.message:exists

msg:exists()

Retorna un booleà que indica si la clau del missatge existeix.

mw.message:isBlank

msg:isBlank()

Retorna un booleà que indica si la clau del missatge té contingut. Retorna true si la clau del missatge no existeix o si el missatge és la cadena buida.

mw.message:isDisabled

msg:isDisabled()

Retorna un booleà que indica si la clau del missatge està desactivada. Retorna true si la clau del missatge no existeix o si el missatge és la cadena buida o la cadena "-".

Biblioteca site (del lloc)

N. del T. hi ha dos conceptes, referits als espais de noms:

• "contingut": a la Viquipèdia és només l'espai dels articles.
• "subjecte": és gairebé equivalent als que no són de discussió.

mw.site.currentVersion

Una cadena que conté la versió actual de MediaWiki.

mw.site.scriptPath

El valor de $wgScriptPath .

mw.site.server

El valor de $wgServer .

mw.site.siteName

El valor de $wgSitename .

mw.site.stylePath

El valor de $wgStylePath .

mw.site.wikiId

A string containing the wiki ID.

mw.site.namespaces

Taula que conté dades per a tots els espais de noms, indexats per número.

Les dades disponibles són:

• id: Número d'espai de noms.
• name: Nom de l'espai de noms local.
• canonicalName: Nom de l'espai de noms canònic.
• displayName: Defineix a l'espai de noms 0, el nom que s'utilitzarà per a la visualització (ja que el nom sovint és la cadena buida).
• hasSubpages: Si les subpàgines estan habilitades per a l'espai de noms.
• hasGenderDistinction: Si l'espai de noms té diferents àlies per a diferents gèneres.
• isCapitalized: Si la primera lletra de les pàgines de l'espai de noms està en majúscula.
• isContent: Si es tracta d'un espai de noms de contingut.
• isIncludable: Si les pàgines de l'espai de noms es poden transcloure.
• isMovable: Si les pàgines de l'espai de noms es poden moure (canviar de nom).
• isSubject: Si es tracta d'un espai de noms de subjecte.
• isTalk: Si es tracta d'un espai de noms de discussió.
• defaultContentModel: El model de contingut per defecte de l'espai de noms, com a cadena.
• aliases: Llista d'àlies per a l'espai de noms.
• subject: Referència a les dades de l'espai de noms de subjecte corresponent.
• talk: Referència a les dades de l'espai de noms de discussió corresponent.
• associated: Referència a les dades de l'espai de noms associat.

També es defineix una metataula que permet cercar espais de noms per nom (localitzat o canònic). Per exemple, tant mw.site.namespaces[4] com mw.site.namespaces.Project retornaran informació sobre l'espai de noms Projecte.

mw.site.contentNamespaces

Taula que només conté els espais de noms de contingut, indexats per número. Vegeu mw.site.namespaces per a més detalls.

mw.site.subjectNamespaces

Taula que només conté els espais de noms de subjecte, indexats per número. Vegeu mw.site.namespaces per a més detalls.

mw.site.talkNamespaces

Taula que només conté els espais de noms de discussió, indexats per número. Vegeu mw.site.namespaces per a més detalls.

mw.site.stats

Taula que conté les estadístiques del lloc. Les estadístiques disponibles són:

• pages: Nombre de pàgines al wiki.
• articles: Nombre de pàgines al wiki.
• files: Nombre de fitxers al wiki.
• edits: Nombre d'edicions al wiki.
• users: Nombre d'usuaris al wiki.
• activeUsers: Nombre d'usuaris actius al wiki.
• admins: Nombre d'usuaris del grup 'sysop' (administradors) al wiki.

mw.site.stats.pagesInCategory

mw.site.stats.pagesInCategory( categoria, que )

Aquesta funció és costosa

Obté estadístiques sobre la categoria. Si which té el valor especial "*", el resultat és una taula amb les propietats següents:

• all: Total de pàgines, fitxers i subcategories.
• subcats: Nombre de subcategories.
• files: Nombre de fitxers.
• pages: Nombre de pàgines.

Si which és una de les claus anteriors ("all", "subcats", "files", "pages"), el resultat és un número amb el valor corresponent.

Cada nova categoria consultada incrementarà el recompte de la funció costosa.

mw.site.stats.pagesInNamespace

mw.site.stats.pagesInNamespace( espai de noms )

Retorna el nombre de pàgines a l'espai de noms donat (especifiqueu-lo per número).

mw.site.stats.usersInGroup

mw.site.stats.usersInGroup( grup )

Retorna el nombre d'usuaris del grup donat.

mw.site.interwikiMap

mw.site.interwikiMap( filtre )

Retorna una taula que conté dades sobre els prefixos interwiki disponibles. Si filter és la cadena "local", només es retornen les dades dels prefixos interwiki locals. Si filter és la cadena "!local", només es retornen les dades dels prefixos no locals. Si no s'especifica cap filtre, es retornen les dades de tots els prefixos. Un prefix "local" en aquest context és aquell que és per al mateix projecte. Per exemple, a la Viquipèdia en anglès, les Viquipèdies en altres idiomes es consideren locals, mentre que el Wiktionary i altres no.

Les claus de la taula retornades per aquesta funció són prefixos interwiki i els valors són subtaules amb les propietats següents:

• prefix - el prefix interwiki.
• url - l'URL a la qual apunta l'interwiki. El nom de la pàgina es representa amb el paràmetre $1.
• isProtocolRelative - un booleà que mostra si l'URL és protocol-relative.
• isLocal - si l'URL és per a un lloc del projecte actual.
• isCurrentWiki - si l'URL és per al wiki actual.
• isTranscludable - si les pàgines que utilitzen aquest prefix interwiki són transcludable. Això requereix transclusió scary, que està desactivada als wikis de Wikimedia.
• isExtraLanguageLink - si l'interwiki apareix a la llista a $wgExtraInterlanguageLinkPrefixes .
• displayText - per als enllaços llistats a $wgExtraInterlanguageLinkPrefixes, aquest és el text que es mostra per a l'enllaç interwiki d'idioma. Nil si no s'especifica.
• tooltip - per als enllaços llistats a $wgExtraInterlanguageLinkPrefixes, aquest és el text de la informació emergent que es mostra quan els usuaris passen el cursor per sobre de l'enllaç interwiki d'idioma. Nil si no s'especifica.

Biblioteca SVG

La biblioteca SVG proporciona una manera de crear imatges SVG representades com a elements ‎<img> en HTML. Els SVG es renderitzen en mode animat segur. Això significa que els scripts i els recursos externs no es renderitzen, però sí que es permeten animacions declaratives com ara SMIL o CSS @keyframe sempre que no necessitin la interacció de l'usuari.

El CSS de la pàgina circumdant no afecta els elements SVG dins del fitxer, de manera que no podeu utilitzar variables CSS com ara --color-base al vostre svg. Tanmateix, podeu utilitzar consultes prefers-color-scheme @media o la funció CSS ​​light-dark() per fer que el mode nocturn de SVG sigui compatible.

Per obtenir documentació sobre com funciona SVG, consulteu MDN.

mw.svg.new

Inicialitza un nou objecte d'imatge SVG. L'objecte retornat té uns quants mètodes:

• setContent( ... ) – Defineix el contingut intern de l'etiqueta ‎<svg>.
• setAttribute( nom, valor ) – Estableix un atribut de l'etiqueta ‎<svg>.
• setImgAttribute( nom, valor ) – Estableix un atribut de l'etiqueta ‎<img> resultant. Els atributs permesos són: width, height, class, id, alt, title, style.
• toImage() – Genera l'etiqueta ‎<img> final. El valor de retorn és un marcador de fragment.

Exemple:

local svg = mw.svg.new()
svg:setAttribute( 'width', '120px' )
	:setAttribute( 'height', '120px' )
	:setContent( '<circle cx="50" cy="50" r="45" style="fill:green;" />' )
	:setImgAttribute( 'alt', 'SVG image' )
	:toImage() -- Gives the image

Això pot ser especialment útil per representar dades de forma dinàmica. Per exemple:

function p.drawGraph()
	-- A series of (x,y) data points to graph
	local points = { "0, 1", "1, 4.5", "3, 2", "5, 4" }

	local pathElm = mw.html.create( 'polyline' )
		:css( 'stroke', 'red' )
		:attr( 'points', table.concat( points, ' ' ) )
		:attr( 'fill', 'none')
		:attr( 'stroke-width', "0.05px")
		-- Circle each point
		:css( 'marker', 'url(#circle)' )

	local axis = mw.html.create( 'path' )
		:css( 'stroke', 'black' )
		-- M means move to point, L means draw line from current point to specified point
		:attr( 'd', 'M 5 -0.1 L -0.1 -0.1 L -0.1 5' )
		:css( 'stroke-width', "0.2px")
		:css( 'stroke-linecap', 'square' )
		:css( 'fill', 'none' )

	-- Circle marker for each data point
	local marker = mw.html.create( 'marker' )
		:attr( 'id', 'circle' )
		:attr( 'markerWidth', '10' )
		:attr( 'markerHeight', '10')
		:attr( 'refX', '5' )
		:attr( 'refY', '5' )
		:tag( 'circle' )
			:attr( { cx = 5, cy = 5, r = 4, stroke = "red", fill = "none" } )
		:done() 
		
	return mw.svg.new()
		:setImgAttribute( 'width', '200' )
		:setAttribute( 'viewBox', "-0.5 -0.5 6, 6" )
		-- Make origin be bottom left
		:setAttribute( 'transform', 'scale(1,-1)')
		:setContent( tostring(axis) .. tostring(marker) .. tostring(pathElm) )
		:toImage()
end

Que produeix:

Biblioteca text

La biblioteca de text proporciona algunes funcions comunes de processament de text que falten a la biblioteca de cadenes i la biblioteca d'Ustring. Aquestes funcions són segures per al seu ús amb cadenes UTF-8.

mw.text.decode

mw.text.decode( cadena )
mw.text.decode( cadena, decodeNamedEntities )

Substitueix Entitats HTML a la cadena amb els caràcters corresponents.

Si el booleà decodeNamedEntities s'omet o és fals, les úniques entitats amb nom reconegudes són < (<), > (>), & (&), " (") i   (l'espai no separable, U+00A0). En cas contrari, la llista d'entitats amb nom HTML5 a reconèixer es carrega des de la funció get_html_translation_table de PHP.

Errors coneguts: Aproximadament 600 del voltant de 2.200 entitats amb nom de l'estàndard HTML5 no es descodifiquen, ni tan sols quan s'utilitza decodeNamedEntities; això inclou aproximadament 40 del voltant de 250 entitats que també s'inclouen a HTML4. Això passa perquè la funció get_html_translation_table de PHP només retorna una correspondència per a cada caràcter, de manera que, per exemple, → no es descodifica, ja que PHP només retorna → com a mapatge per a →.

mw.text.encode

mw.text.encode( cadena )
mw.text.encode( cadena, joc de caràcters )

Substitueix els caràcters d'una cadena per entitats HTML. Cinc caràcters se substitueixen per les entitats amb nom corresponents: <, >, &, " i l'espai inseparable (U+00A0). Tots els altres se substitueixen per entitats numèriques.

Si es proporciona charset, hauria de ser una cadena segons correspongui per anar entre claudàtors en un patró Ustring, és a dir, el "conjunt" de [set]. El conjunt de caràcters per defecte conté sis caràcters: <, >, &, ", ' i l'espai inseparable (U+00A0).

mw.text.jsonDecode

mw.text.jsonDecode( cadena )
mw.text.jsonDecode( cadena, indicadors )

Descodifica una cadena JSON. flags és 0 o una combinació (feu servir +) dels indicadors mw.text.JSON_PRESERVE_KEYS i mw.text.JSON_TRY_FIXING.

Normalment, les matrius de base zero de JSON es tornen a numerar a taules de seqüència de base u de Lua; per evitar-ho, passeu mw.text.JSON_PRESERVE_KEYS.

Per relaxar certs requisits de JSON, com ara no tenir coma terminal en matrius o objectes, passeu mw.text.JSON_TRY_FIXING. Això no es recomana.

Limitacions:

• Les matrius JSON descodificades poden no ser seqüències Lua si la matriu conté valors nuls.
• Els objectes JSON eliminaran claus que tinguin valors nuls.
• No és possible saber directament si l'entrada era una matriu JSON o un objecte JSON amb claus enteres seqüencials.
• Un objecte JSON que tingui claus enteres seqüencials que comencen per 1 es descodificarà a la mateixa estructura de taula que una matriu JSON amb els mateixos valors, tot i que aquests no siguin gens equivalents, tret que s'utilitzi mw.text.JSON_PRESERVE_KEYS.

mw.text.jsonEncode

mw.text.jsonEncode( valor )
mw.text.jsonEncode( valor, indicadors )

Codifica una cadena JSON. Es generen errors si el valor passat no es pot codificar en JSON. flags és 0 o una combinació (utilitzeu +) dels indicadors mw.text.JSON_PRESERVE_KEYS i mw.text.JSON_PRETTY.

Normalment, les taules de seqüència de base u de Lua es codifiquen com a matrius JSON basades en zero; quan mw.text.JSON_PRESERVE_KEYS s'estableix a flags, les taules de seqüència de base zero es codifiquen com a matrius JSON.

Limitacions:

• Les taules buides sempre es codifiquen com a matrius buides ([]), no com a objectes buits ({}).
• Les taules de seqüència no es poden codificar com a objectes JSON sense afegir un element "ninot".
• Per produir objectes o matrius amb valors nuls, cal una implementació complicada del metamètode __pairs.
• Una taula Lua que tingui claus enteres seqüencials que comencen per 0 es codificarà com a matriu JSON, igual que una taula Lua que tingui claus enteres que comencen per 1, tret que s'utilitzi mw.text.JSON_PRESERVE_KEYS.
• Quan tant un número com la representació de cadena d'aquest número s'utilitzen com a claus a la mateixa taula, el comportament no és especificat.

mw.text.killMarkers

mw.text.killMarkers( cadena )

Elimina tots els marcadors de fragments de MediaWiki d'una cadena.

mw.text.listToText

mw.text.listToText( llista )
mw.text.listToText( llista, separador, conjunció )

Uneix una llista, a l'estil de prosa. En altres paraules, és com table.concat() però amb un separador diferent abans de l'element final.

El separador per defecte es pren de MediaWiki:comma-separator en l'idioma del contingut del wiki, i la conjunció per defecte és MediaWiki:and concatenada amb MediaWiki:word-separator.

Exemples, utilitzant els valors per defecte per als missatges:

 -- Retorna la cadena buida
 mw.text.listToText( {} )
 
 -- Retorna "1"
 mw.text.listToText( { 1 } )
 
 -- Retorna "1 i 2"
 mw.text.listToText( { 1, 2 } )
 
 -- Retorna "1, 2, 3, 4 i 5"
 mw.text.listToText( { 1, 2, 3, 4, 5 } )
 
 -- Retorna "1; 2; 3; 4 or 5"
 mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' or ' )

mw.text.nowiki

mw.text.nowiki( cadena )

Substitueix diversos caràcters de la cadena per entitats HTML per evitar la seva interpretació com a wikitext. Això inclou:

• Els caràcters següents: ", &, ', <, =, >, [, ], {, | i }
• Els caràcters següents al principi de la cadena o immediatament després d'un salt de línia: #, *, :, ;, space, tab (\t)
• Les línies en blanc tindran un dels caràcters de salt de línia o retorn de carro associats com a escapada
• ---- al principi de la cadena o immediatament després d'un salt de línia tindrà el primer - com a escapada
• __ tindrà un subratllat com a escapada
• :// tindrà els dos punts com a escapada
• S'escaparà un caràcter d'espai en blanc després de ISBN, RFC, PMID

mw.text.split

mw.text.split( cadena, patró, pla )

Divideix la cadena en subcadenes als límits que coincideixin amb el patró Ustring pattern. Si s'especifica plain i true, pattern s'interpretarà com una cadena literal en lloc de com un patró Lua (igual que amb el paràmetre del mateix nom per a mw.ustring.find()). Retorna una taula que conté les subcadenes.

Per exemple, mw.text.split( 'a b\tc\nd', '%s' ) retornaria una taula { 'a', 'b', 'c', 'd' }.

Si pattern coincideix amb la cadena buida, string es dividirà en caràcters individuals.

Tingueu en compte que aquesta funció pot ser més de 60 vegades més lenta que una reimplementació que no sigui compatible amb Unicode, com ara la següent:

function split(text, pattern, plain)
    local ret = {}
    local s, l = 1, string.len( text )
    while s do
    	local e, n = string.find( text, pattern, s, plain )
    	if not e then
    		ret[#ret+1] = string.sub ( text, s )
    		s = nil
    	elseif n < e then
    		-- Separador buit!
    		ret[#ret+1] = string.sub ( text, s, e )
    		if e < l then
    			s = e + 1
    		else
    			s = nil
    		end
    	else
    		ret[#ret+1] = e > s and string.sub( text, s, e - 1 ) or ''
    		s = n + 1
    	end
    end
    return ret
end

mw.text.gsplit

mw.text.gsplit( cadena, patró, pla )

Retorna una funció iteradora que iterarà sobre les subcadenes que retornaria la crida equivalent a mw.text.split().

Tingueu en compte que aquesta funció pot ser més de 60 vegades més lenta que una reimplementació que no sigui compatible amb Unicode, com ara la següent:

function gsplit( text, pattern, plain )
	local s, l = 1, string.len( text )
	return function ()
		if s then
			local e, n = string.find( text, pattern, s, plain )
			local ret
			if not e then
				ret = string.sub( text, s )
				s = nil
			elseif n < e then
				-- Separador buit!
				ret = string.sub( text, s, e )
				if e < l then
					s = e + 1
				else
					s = nil
				end
			else
				ret = e > s and string.sub( text, s, e - 1 ) or ''
				s = n + 1
			end
			return ret
		end
	end, nil, nil
end

mw.text.tag

mw.text.tag( name, attrs, content )
mw.text.tag{ name = cadena, attrs = taula, content = cadena|false }

Tingueu en compte l'ús d'arguments amb nom.

Genera una etiqueta d'estil HTML per a name.

Si es proporciona attrs, ha de ser una taula amb claus de cadena. Els valors de cadena i numèrics s'utilitzen com a valor de l'atribut; el booleà true fa que la clau es mostri com un paràmetre sense valor HTML5; el booleà false omet completament la clau; i qualsevol altra cosa és un error.

Si no es proporciona content (o és nil), només es retorna l'etiqueta d'obertura. Si content és booleà false, es retorna una etiqueta autotancada. En cas contrari, ha de ser una cadena o un número, en aquest cas aquest contingut s'inclou a l'etiqueta d'obertura i tancament construïda. Tingueu en compte que el contingut no es codifica automàticament en HTML; utilitzeu mw.text.encode() si cal.

Per retornar correctament etiquetes d'extensió com ara ‎<ref>, utilitzeu frame:extensionTag() en comptes d'això.

mw.text.trim

mw.text.trim( cadena )
mw.text.trim( cadena, charset )

Elimina els espais en blanc o altres caràcters del principi i del final d'una cadena.

Si es proporciona charset, hauria de ser una cadena segons correspongui per anar entre claudàtors en un patró Ustring, és a dir, el "set" a [set]. El charset (joc de caràcters) per defecte és l'espai en blanc ASCII, %s, que equival a "\t\r\n\f\v ".

mw.text.truncate

mw.text.truncate( text, longitud )
mw.text.truncate( text, longitud, ellipsis )
mw.text.truncate( text, longitud, ellipsis, adjustLength )

Trunca text a la longitud especificada en punts de codi, afegint ellipsis [N. del T. ellipsis es refereix, per defecte, a tres punts suspensius o altre cadena que s'assigni] si s'ha realitzat un truncament. Si la longitud és positiva, el final de la cadena es truncarà; si és negativa, s'eliminarà el principi. Si es dona adjustLength i true, la cadena resultant, incloent-hi l'ellipsis, no serà més llarga que la longitud especificada.

El valor per defecte de ellipsis es pren de MediaWiki:ellipsis a l'idioma del contingut del wiki.

Exemples, utilitzant els punts suspensius per defecte "...":

-- Retorna "foobarbaz"
mw.text.truncate( "foobarbaz", 9 )

-- Retorna "fooba..."
mw.text.truncate( "foobarbaz", 5 )

-- Retorna "...arbaz"
mw.text.truncate( "foobarbaz", -5 )

-- Retorna "foo..."
mw.text.truncate( "foobarbaz", 6, nil, true )

-- Retorna "foobarbaz", perquè és més curt que "foobarba..."
mw.text.truncate( "foobarbaz", 8 )

mw.text.unstripNoWiki

mw.text.unstripNoWiki( cadena )

Substitueix els marcadors de fragment de MediaWiki <nowiki> pel text corresponent. Altres tipus de marcadors de fragment no es modifiquen.

mw.text.unstrip

mw.text.unstrip( cadena )

Equivalent a mw.text.killMarkers( mw.text.unstripNoWiki( string )).

Això ja no revela l'HTML darrere de la transclusió de pàgines especials, les etiquetes <ref>, etc., com feia a les versions anteriors de Scribunto.

Biblioteca de títols

mw.title redirects here. You might be looking for the JavaScript library called "mw.Title".

mw.title.equals

mw.title.equals( a, b )

Comprova si dos títols són iguals. Tingueu en compte que els fragments s'ignoren en la comparació.

mw.title.compare

mw.title.compare( a, b )

Retorna -1, 0 o 1 per indicar si el títol a és menor, igual o major que el títol b.

Això compara els títols per prefix interwiki (si n'hi ha) com a cadenes, després per número d'espai de noms i després pel text del títol sense prefix com a cadena. Aquestes comparacions de cadenes utilitzen l'operador < estàndard de Lua.

mw.title.getCurrentTitle

mw.title.getCurrentTitle()

Retorna l'objecte de títol per a la pàgina actual.

mw.title.new

mw.title.new( text, espai de noms )
mw.title.new( ID )

Aquesta funció és costosa quan es crida amb un ID

Crea un nou objecte de títol.

Si es dona un número ID, es crea un objecte per al títol amb aquest page_id. El títol al qual es fa referència es comptarà com a enllaçat des de la pàgina actual. Si el page_id no existeix, retorna zero. El recompte de funcions costoses s'incrementarà si l'objecte de títol creat no és per a un títol que ja s'ha carregat.

Si es proporciona una cadena text en comptes d'això, es crea un objecte per a aquell títol (fins i tot si la pàgina no existeix). Si la cadena de text no especifica un espai de noms, s'utilitzarà namespace (que pot ser qualsevol clau que es trobi a mw.site.namespaces). Si el text no és un títol vàlid, es retorna zero.

mw.title.newBatch

mw.title.newBatch{ primeraPàgina, segonaPàgina, terceraPàgina }

mw.title.newBatch( { primeraPàgina, segonaPàgina, terceraPàgina }, EspaiDeNomsPredeterminat )

Aquesta funció pot ser costosa. mw.title.newBatch( listOfPages ):lookupExistence():getTitles() incrementarà el recompte de funcions costoses una vegada per cada 25 elements que necessiti cercar.

Crea un lot de títols per cercar. El primer argument és una llista de títols de pàgina a cercar. La llista només ha de contenir cadenes; actualment no es permet utilitzar números tal com està permès amb mw.title.new. El segon argument opcional és l'espai de noms per defecte que s'utilitzarà quan es busca el títol de la pàgina.

Aquest mètode retornarà un objecte de cerca per lots amb dos mètodes: lookupExistence i getTitles. Cridar lookupExistence() sol·licita que la cerca per lots ompli els camps .exists, .contentModel, .id i .isRedirect dels objectes de títol. getTitles() retornarà una taula amb objectes de títol. Qualsevol títol no vàlid serà nul a la taula. Els títols de l'espai de noms multimèdia no tindran .exists emplenats.

Per exemple:

-- The following will increment once
local titles = mw.title.newBatch{
  "First page",
  "User:Bob",
  "Second page" }:lookupExistence():getTitles()

-- the following will not increment the counter
titles[1].exists
titles[2].id

mw.title.makeTitle

mw.title.makeTitle( namespace, title, fragment, interwiki )

Crea un objecte de títol amb el títol title a l'espai de noms namespace, opcionalment amb els prefixos fragment i interwiki especificats. namespace pot ser qualsevol clau que es trobi a mw.site.namespaces. Si el títol resultant no és vàlid, retorna nil.

Tingueu en compte que, a diferència de mw.title.new(), aquest mètode sempre aplicarà l'espai de noms especificat. Per exemple, mw.title.makeTitle( 'Template', 'Module:Foo' ) crearà un objecte per a la pàgina Template:Module:Foo, mentre que mw.title.new( 'Module:Foo', 'Template' ) crearà un objecte per a la pàgina Module:Foo.

Tingueu en compte també que la funcionalitat dels títols interwiki està limitada a interwiki / isExternal / isLocal i als mètodes relacionats amb l'URL; és possible que altres mètodes no es comportin com s'espera.

Objectes title

Un objecte de títol té diverses propietats i mètodes. La majoria de les propietats són de només lectura.

Tingueu en compte que els camps que acaben amb text retornen títols com a valors de cadena, mentre que els camps que acaben amb title retornen objectes de títol.

• id: El page_id. 0 si la pàgina no existeix. Això pot ser costós.
• interwiki: El prefix interwiki o la cadena buida si no n'hi ha.
• namespace: El número d'espai de noms.
• fragment: El fragment (també conegut com a enllaç de secció/àncora) o la cadena buida. Es pot assignar.
• nsText: El text de l'espai de noms de la pàgina.
• subjectNsText: El text de l'espai de noms de subjecte.
• talkNsText: El text de l'espai de noms de discussió de la pàgina, o nil si aquest títol no pot tenir una pàgina de discussió. (afegit a MediaWiki 1.42.0-wmf.15, refs. T180911)
• text: El títol de la pàgina, sense els prefixos de l'espai de noms ni els prefixos interwiki.
• prefixedText: El títol de la pàgina, amb els prefixos de l'espai de noms i l'interwiki.
• fullText: El títol de la pàgina, amb els prefixos de l'espai de noms i l'interwiki i el fragment. No es retorna l'interwiki si és igual a l'actual.
• rootText: Si es tracta d'una subpàgina, la primera part de title.text (abans de la primera barra). Altrament, el mateix que title.text.
• baseText: Si es tracta d'una subpàgina, el text del títol sense subpageText (sense l'última part). Altrament, el mateix que title.text.
• subpageText: Si es tracta d'una subpàgina, només el nom de la subpàgina (després de l'última barra). Altrament, el mateix que title.text.
• canTalk: Si la pàgina d'aquest títol podria tenir una pàgina de discussió.
• exists: Si la pàgina existeix. Àlies per a file.exists per a títols d'espai de noms multimèdia. Per a títols d'espai de noms de fitxer, això comprova l'existència de la pàgina de descripció del fitxer, no del fitxer en si. Això pot ser costós.
• file, fileExists: Vegeu #Metadades del fitxer a continuació.
• isContentPage: Si aquest títol es troba en un espai de noms de contingut [N. del T. vegeu el significat de contingut més amunt].
• isExternal: Si aquest títol té un prefix interwiki.
• isLocal: Si aquest títol es troba en aquest projecte. Per exemple, a la Viquipèdia en anglès, qualsevol altra Viquipèdia es considera "local" mentre que Wiktionary i similars no ho són.
• isRedirect: Si aquest és el títol d'una pàgina que és una redirecció. Això pot ser costós.
• isSpecialPage: Si aquest és el títol d'una possible pàgina especial (és a dir, una pàgina a l'espai de noms Special:).
• isSubpage: Si aquest títol és una subpàgina d'algun altre títol.
• isTalkPage: Indica si aquest és un títol per a una pàgina de discussió.
• isSubpageOf( títol2 ): Indica si aquest títol és una subpàgina del títol donat.
• inNamespace( espai_de_noms ): Indica si aquest títol es troba a l'espai de noms donat. Els espais de noms es poden especificar mitjançant qualsevol cosa que sigui una clau que es trobi a mw.site.namespaces.
• inNamespaces( ... ): Indica si aquest títol es troba en qualsevol dels espais de noms donats. Els espais de noms es poden especificar mitjançant qualsevol cosa que sigui una clau que es trobi a mw.site.namespaces.
• hasSubjectNamespace( espai_de_noms ): Indica si l'espai de noms de subjecte d'aquest títol es troba a l'espai de noms donat. Els espais de noms es poden especificar mitjançant qualsevol cosa que sigui una clau que es trobi a mw.site.namespaces.
• contentModel: El model de contingut per a aquest títol, com a cadena. Per a una pàgina que no existeix, aquest és el model de contingut que rebria en crear-se. Això pot ser costós.

• basePageTitle: El mateix que mw.title.makeTitle( title.namespace, title.baseText ).
• rootPageTitle: El mateix que mw.title.makeTitle( title.namespace, title.rootText ).
• talkPageTitle: El mateix que mw.title.makeTitle( mw.site.namespaces[title.namespace].talk.id, title.text ), o nil si aquest títol no pot tenir una pàgina de discussió.
• subjectPageTitle: El mateix que mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text ).
• redirectTarget: Retorna un objecte de títol de la destinació de la pàgina de redirecció si la pàgina és una redirecció, retorna false en cas contrari.
• protectionLevels: Els nivells de protecció de la pàgina. Aquesta és una taula amb claus corresponents a cada acció (per exemple, "edit" i "move"). Els valors de la taula són matrius, el primer element del qual és una cadena que conté el nivell de protecció. Si la pàgina no està protegida, els valors de la taula o els elements de la matriu seran nil. Això és costós.
• cascadingProtection: Les proteccions en cascada aplicables a la pàgina. Aquesta és una taula amb les claus "restrictions" (en si mateixa una taula amb claus com la que té protectionLevels) i "sources" (una matriu que enumera els títols des d'on es produeixen les proteccions en cascada). Si no hi ha proteccions en cascada a la pàgina, "restrictions" i "sources" estaran buits. Això és costós.
• categories: (des de v1.43.0-wmf.18) La llista de categories utilitzades a la pàgina. Això és costós
• subPageTitle( text ): El mateix que mw.title.makeTitle( title.namespace, title.text .. '/' .. text ).
• partialUrl(): Retorna title.text codificat com ho faria en un URL.
• fullUrl( consulta, proto ): Retorna l'URL complet (amb taula/cadena de consulta opcional) per a aquest títol. Es pot especificar proto per controlar l'esquema de l'URL resultant: "http", "https", "relative" (per defecte) o "canonical".
• localUrl( consulta ): Retorna l'URL local (amb taula/cadena de consulta opcional) per a aquest títol.
• canonicalUrl( consulta ): Retorna l'URL canònic (amb taula/cadena de consulta opcional) per a aquest títol.
• content o getContent(): Retorna el contingut (sense analitzar) de la pàgina o nil si no hi ha cap pàgina. La pàgina es registrarà com una transclusió.
• pageLang: Un objecte d'idioma per a l'idioma del contingut de la pàgina del títol, que per defecte és l'idioma del contingut del wiki. Això és costós.

Algunes propietats també s'afegeixen amb extensions:

• isDisambiguationPage: (Provided by Extension:Disambiguator) Returns true for disambiguation pages. This is expensive.
• pageAssessments: (Provided by Extension:PageAssessments) Returns the names of WikiProjects associated with the page along with their class and importance assessments. This is expensive.
• pageImage: (Provided by Extension:PageImages) Returns the name of the file selected as the image that is shown in search results and related article lists. This is expensive.

Els objectes de títol es poden comparar mitjançant operadors relacionals. tostring( title ) retornarà title.prefixedText.

Tingueu en compte que accedir a qualsevol camp costós d'un objecte de títol registra un "enllaç" a la pàgina (com es mostra a Special:WhatLinksHere, per exemple). L'ús del mètode getContent() de l'objecte de títol o l'accés al camp redirectTarget el registra com a camps file o fileExists registrant-lo com a "enllaç a fitxer".

Metadades de fitxer

Els objectes de títol que representen una pàgina a l'espai de noms File o Media tindran una propietat anomenada file. Això és costós i es registrarà com a un ús de fitxer si el fitxer existeix. Aquesta és una taula, estructurada de la següent manera:

• exists: Si el fitxer existeix. La propietat fileExists d'un objecte Title existeix per motius de compatibilitat amb versions anteriors i és un àlies per a aquesta propietat. Si això és false, totes les altres propietats del fitxer seran nil.
• width: L'amplada del fitxer. Si el fitxer conté diverses pàgines, aquesta és l'amplada de la primera pàgina.
• height: L'alçada del fitxer. Si el fitxer conté diverses pàgines, aquesta és l'alçada de la primera pàgina.
• pages: Si el format de fitxer admet diverses pàgines, aquesta és una taula que conté taules per a cada pàgina del fitxer; en cas contrari, és nil. L'operador # es pot utilitzar per obtenir el nombre de pàgines del fitxer. Cada taula de pàgines individual conté una propietat width (amplada) i height (alçada).
• size: La mida del fitxer en bytes.
• mimeType: El tipus MIME o de mitjà ​​del fitxer.
• length: La longitud (durada) del fitxer multimèdia en segons. Zero per als tipus multimèdia que no admeten longitud.
• metadata: Metadades incrustades (per exemple, Exif) del fitxer. Això és costós

Propietats costoses

Les propietats id, isRedirect, exists i contentModel requereixen obtenir dades sobre el títol de la base de dades. Per aquest motiu, el recompte de funcions costoses s'incrementa la primera vegada que s'accedeix a una d'elles per a una pàgina diferent de la pàgina actual. Els accessos posteriors a qualsevol d'aquestes propietats per a aquesta pàgina no tornaran a incrementar el recompte de funcions costoses. Si teniu diverses pàgines, heu de conèixer aquestes propietats, ja que podeu utilitzar mw.title.newBatch per cercar fins a 25 pàgines alhora mentre només incrementeu el recompte de funcions costoses una vegada.

Altres propietats marcades com a costoses sempre incrementaran el recompte de funcions costoses la primera vegada que s'hi accedeixi per a una pàgina diferent de la pàgina actual.

Biblioteca URI

mw.uri.encode

mw.uri.encode( cadena, tipus_codificació )

Codifica percentualment la cadena. El tipus per defecte, "QUERY", codifica els espais utilitzant '+' per al seu ús en cadenes de consulta; "PATH" codifica els espais com a %20; i "WIKI" codifica els espais com a '_'.

Tingueu en compte que el format "WIKI" no és completament reversible, ja que tant els espais com els subratllats es codifiquen com a '_'.

mw.uri.decode

mw.uri.decode( cadena, tipus_codificació )

Descodifica percentualment la cadena. El tipus per defecte, "QUERY", descodifica '+' a espai; "PATH" no realitza cap descodificació addicional; i "WIKI" descodifica '_' a espai.

mw.uri.anchorEncode

mw.uri.anchorEncode( cadena )

Codifica una cadena per al seu ús en un fragment URI de MediaWiki.

mw.uri.buildQueryString

mw.uri.buildQueryString( taula )

Codifica una taula com una cadena de consulta URI. Les claus han de ser cadenes; els valors poden ser cadenes o números, taules seqüencials o el booleà false.

mw.uri.parseQueryString

mw.uri.parseQueryString( s, i, j )

Descodifica la cadena de consulta s a una taula. Les claus de la cadena sense valors tindran un valor de false; les claus repetides diverses vegades tindran taules seqüencials com a valors; i altres tindran cadenes com a valors.

Els arguments numèrics opcionals i i j es poden utilitzar per especificar una subcadena de s que s'hagi d'analitzar, en lloc de la cadena sencera. i és la posició del primer caràcter de la subcadena i per defecte és 1. j és la posició de l'últim caràcter de la subcadena i per defecte és la longitud de la cadena. Tant i com j poden ser negatius, com en string.sub.

mw.uri.canonicalUrl

mw.uri.canonicalUrl( pàgina, consulta )

Retorna un objecte URI per a l'URL complet d'una pàgina, amb una cadena/taula de consulta, opcionals.

mw.uri.fullUrl

mw.uri.fullUrl( pàgina, consulta )

Retorna un objecte URI per a l'URL complet d'una pàgina, amb una cadena/taula de consulta, opcionals.

mw.uri.localUrl

mw.uri.localUrl( pàgina, consulta )

Retorna un objecte URI per a l'URL local d'una pàgina, amb una cadena/taula de consulta, opcionals.

mw.uri.new

mw.uri.new( cadena )

Construeix un nou objecte URI per a la cadena o taula passades. Vegeu la descripció dels objectes URI per conèixer els possibles camps de la taula.

mw.uri.validate

mw.uri.validate( taula )

Valida la taula (o objecte URI) passat. Retorna un booleà que indica si la taula era vàlida i, en cas d'error, una cadena que explica quins problemes s'han trobat.

Objecte URI

L'objecte URI té els camps següents, alguns o tots els quals poden ser nil:

• protocol: Cadena protocol/esquema
• user: Cadena de l'usuari
• password: Cadena de la contrasenya
• host: Cadena del nom de l'amfitrió
• port: Port enter
• path: Cadena del camí
• query: Una taula, a partir de mw.uri.parseQueryString
• fragment: Fragment de cadena.

Les propietats següents també estan disponibles:

• userInfo: Cadena de l'usuari i la contrasenya
• hostPort: Cadena de l'amfitrió i el port
• authority: Cadena de l'usuari, contrasenya, host i port
• queryString: Versió de la taula de consultes en forma de cadena
• relativePath: Cadena del camí, cadena de la consulta i fragment

tostring() donarà la cadena URI.

Els mètodes de l'objecte URI són:

mw.uri:parse

uri:parse( cadena )

Analitza una cadena a l'objecte URI actual. Els camps especificats a la cadena se substituiran a l'objecte actual; els camps no especificats conservaran els seus valors antics.

mw.uri:clone

uri:clone()

Fa una còpia de l'objecte URI.

mw.uri:extend

uri:extend( paràmetres )

Fusiona la taula de paràmetres amb la taula de consultes de l'objecte.

Biblioteca ustring

La biblioteca ustring està pensada per ser una reimplementació directa de la Biblioteca String estàndard, excepte que els mètodes operen amb caràcters en cadenes codificades en UTF-8 en lloc de bytes.

La majoria de funcions generaran un error si la cadena no és UTF-8 vàlida; s'indiquen les excepcions.

mw.ustring.maxPatternLength

La longitud màxima permesa d'un patró, en bytes.

mw.ustring.maxStringLength

La longitud màxima permesa d'una cadena, en bytes.

mw.ustring.byte

mw.ustring.byte( s, i, j )

Retorna els bytes individuals; idèntic a string.byte().

mw.ustring.byteoffset

mw.ustring.byteoffset( s, l, i )

Retorna l'òfset de bytes d'un caràcter de la cadena. El valor per defecte tant per a l com per a i és 1. i pot ser negatiu, en aquest cas compta des del final de la cadena.

El caràcter a l == 1 és el primer caràcter que comença al byte i o després; El caràcter a l == 0 és el primer caràcter que comença al byte i o abans. Tingueu en compte que pot ser el mateix caràcter. Els valors més grans o més petits de l es calculen en relació amb aquests.

mw.ustring.char

mw.ustring.char( ... )

Molt semblant a string.char(), excepte que els enters són punts de codi Unicode en lloc de valors de bytes.

local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- El valor ara és 'Привет!'

mw.ustring.codepoint

mw.ustring.codepoint( s, i, j )

Molt semblant a string.byte(), excepte que els valors de retorn són punts de codi i els òfsets són caràcters en lloc de bytes.

mw.ustring.find

mw.ustring.find( s, pattern, init, plain )

Molt semblant a string.find(), excepte que el patró s'estén tal com es descriu a Patrons Ustring i el desplaçament init és en caràcters en lloc de bytes.

mw.ustring.format

mw.ustring.format( format, ... )

Idèntic a string.format(). Les amplades i les precisions de les cadenes s'expressen en bytes, no en punts de codi.

mw.ustring.gcodepoint

mw.ustring.gcodepoint( s, i, j )

Retorna tres valors per iterar sobre els punts de codi de la cadena. i té el valor per defecte 1 i j és -1. Això està pensat per al seu ús en la forma iterador de for:

for codepoint in mw.ustring.gcodepoint( s ) do
     -- bloc
end

mw.ustring.gmatch

mw.ustring.gmatch( s, pattern )

Molt semblant a string.gmatch(), excepte que el patró s'estén tal com es descriu a Patrons Ustring.

Error conegut - Quan s'utilitza amb un patró que pot coincidir amb la cadena buida, la funció es quedarà encallada en un bucle infinit. Per exemple, el bucle següent no acaba mai:

for capture in mw.ustring.gmatch( "foo bar", ".*" ) do
     -- bloc
end

mw.ustring.gsub

mw.ustring.gsub( s, pattern, repl, n )

Molt semblant a string.gsub(), excepte que el patró és estès tal com es descriu a Patrons Ustring.

Errors coneguts: Quan repl és una taula, és possible utilitzar números com a claus en lloc de cadenes (per exemple, per substituir instàncies de "5" en una cadena, s'utilitzaria el valor de la clau [5] o ["5"]); per tant, la sortida no és predictible si tenen valors diferents (no nil). Això no és un problema per a string.gsub(), que ignora qualsevol número com a clau.

mw.ustring.isutf8

mw.ustring.isutf8( cadena )

Retorna true si la cadena és UTF-8 vàlida, false si no.

mw.ustring.len

mw.ustring.len( cadena )

Retorna la longitud de la cadena en punts de codi o nil si la cadena no és UTF-8 vàlida.

Vegeu string.len() per a una funció similar que utilitza la longitud de bytes en lloc de punts de codi.

mw.ustring.lower

mw.ustring.lower( cadena )

Molt semblant a string.lower(), excepte que tots els caràcters que són minúscules es converteixen a majúscules segons Unicode.

Si també es carrega la Biblioteca d'idiomes, aquest en comptes d'això cridarà lc() a l'objecte d'idioma per defecte.

mw.ustring.match

mw.ustring.match( s, pattern, init )

Molt semblant a string.match(), excepte que el patró s'estén tal com es descriu a Patrons Ustring i l'òfset init és en caràcters en lloc de bytes.

mw.ustring.rep

mw.ustring.rep( cadena, n )

Idèntic a string.rep().

mw.ustring.sub

mw.ustring.sub( s, i, j )

Molt semblant a string.sub(), excepte que els òfsets són caràcters en lloc de bytes.

mw.ustring.toNFC

mw.ustring.toNFC( cadena )

Converteix la cadena a forma de normalització C (també coneguda com a Composició canònica de la forma de normalització). Retorna nil si la cadena no és una UTF-8 vàlida.

mw.ustring.toNFD

mw.ustring.toNFD( s )

Converteix la cadena a forma de normalització D (també coneguda com a Descomposició canònica de la forma de normalització). Retorna nil si la cadena no és una UTF-8 vàlida.

mw.ustring.toNFKC

mw.ustring.toNFKC( s )

Converteix la cadena a forma de normalització KC (també coneguda com a Composició de compatibilitat de la forma de normalització). Retorna nil si la cadena no és una UTF-8 vàlida.

mw.ustring.toNFKD

mw.ustring.toNFKD( s )

Converteix la cadena a forma de normalització KD (també coneguda com a Descomposició de compatibilitat de la forma de normalització). Retorna nil si la cadena no és una UTF-8 vàlida.

mw.ustring.upper

mw.ustring.upper( s )

Molt semblant a string.upper(), excepte que tots els caràcters que són majúscules es converteixen a minúscules segons Unicode.

Si també es carrega la Biblioteca d'idiomes, en comptes d'això, es cridarà uc() a l'objecte d'idioma per defecte.

Patrons ustring

Els patrons de les funcions ustring utilitzen la mateixa sintaxi que els patrons de la biblioteca String. La principal diferència és que les classes de caràcters es redefineixen en termes de propietats de caràcters Unicode:

• %a: representa tots els caràcters amb la categoria general "Letter" ("Lletra").
• %c: representa tots els caràcters amb la categoria general "Control".
• %d: representa tots els caràcters amb la categoria general "Number, decimal digit" ("Número, dígit decimal").
• %l: representa tots els caràcters amb la categoria general "Lowercase Letter" ("Lletra minúscula").
• %p: representa tots els caràcters amb la categoria general "Punctuation" ("Puntuació").
• %s: representa tots els caràcters amb la categoria general "Separator" ("Separador"), a més de tabulació, salt de línia, retorn de carro, tabulació vertical i salt de pàgina.
• %u: representa tots els caràcters amb la categoria general "Uppercase Letter" ("Lletra Majúscula").
• %w: representa tots els caràcters amb la categoria general "Letter" ("Lletra") o "Decimal Number" ("Número decimal").
• %x: afegeix versions de caràcters d'amplada completa dels dígits hexadecimals.

Igual que en Patrons de biblioteca de cadenes, %A, %C, %D, %L, %P, %S, %U, %W i %X aquí representa el conjunt complementari ("tots els caràcters sense la Categoria General donada").

En tots els casos, els caràcters s'interpreten com a caràcters Unicode en lloc de bytes, de manera que els rangs com ara [０-９], els patrons com ara %b«» i els quantificadors aplicats a caràcters multibyte funcionaran correctament. Les captures buides capturaran la posició en punts de codi en lloc de bytes.

Limitacions conegudes: A diferència de Patrons de biblioteca de cadenes, els patrons de biblioteca Ustring tenen una longitud màxima de 10.000 bytes. Si el patró supera aquesta longitud, la funció Ustring generarà un error. Com que la biblioteca String té el seu propi màxim de 32 captures (a diferència de la biblioteca Ustring), és impossible utilitzar un patró que superi ambdós límits, ja que serà incompatible amb ambdues biblioteques.

Els 9 caràcters ASCII, $, +, <, =, >, ^, `, |, ~, poden coincidir amb %p a la biblioteca de cadenes però no a la biblioteca ustring, ja que Unicode els classifica com a "Symbols" ("Símbols") en lloc de "Punctuation" ("Puntuació").

Biblioteques carregables

Aquestes biblioteques no s'inclouen per defecte, però si cal es poden carregar mitjançant require().

bit32

Aquesta emulació de la biblioteca Lua 5.2 bit32 es pot carregar mitjançant:

 bit32 = require( 'bit32' )

La biblioteca bit32 proporciona operacions bit a bit en enters de 32 bits sense signe. Els números d'entrada es trunquen a enters (de manera no especificada) i es redueixen al mòdul 2³², de manera que el valor estigui en el rang de 0 a 2³²−1; els valors de retorn també es troben en aquest rang.

Quan els bits estan numerats (com en bit32.extract()), 0 és el bit menys significatiu (el que té el valor 2⁰) i 31 és el més significatiu (el que té el valor 2³¹).

bit32.band

bit32.band( ... )

Retorna l'AND bit a bit dels seus arguments: el resultat només té un bit definit si aquest bit està definit en tots els arguments.

Si es donen zero arguments, el resultat té tots els bits establerts.

bit32.bnot

bit32.bnot( x )

Retorna el complement bit a bit de x.

bit32.bor

bit32.bor( ... )

Retorna l'OR bit a bit dels seus arguments: el resultat té un bit definit si aquest bit està definit en qualsevol dels arguments.

Si es donen zero arguments, el resultat té tots els bits nets (zeros).

bit32.btest

bit32.btest( ... )

Equivalent a bit32.band( ... ) ~= 0

bit32.bxor

bit32.bxor( ... )

Retorna el XOR bit a bit dels seus arguments: el resultat té un bit definit si aquest bit està definit en un nombre senar d'arguments.

Si es donen zero arguments, el resultat té tots els bits nets (zeros).

bit32.extract

bit32.extract( n, camp, amplada )

Extreu els bits de amplada de n, començant pel bit camp. Voler accedir a bits fora del rang de 0 a 31 és un error.

Si no s'especifica, el valor per defecte per a amplada és 1.

bit32.replace

bit32.replace( n, v, camp, amplada )

Substitueix els bits de amplada a n, començant pel bit camp, pels bits de amplada baixos de v. Voler accedir a bits fora del rang de 0 a 31 és un error.

Si no s'especifica, el valor per defecte per a amplada és 1.

bit32.lshift

bit32.lshift( n, disp )

Retorna el número n desplaçat disp bits a l'esquerra. Això és un desplaçament lògic: els bits inserits són 0. Això generalment equival a multiplicar per 2^disp.

Tingueu en compte que un desplaçament per sobre de 31 donarà com a resultat 0.

bit32.rshift

bit32.rshift( n, disp )

Retorna el número n desplaçat disp bits a la dreta. Això és un desplaçament lògic: els bits inserits són 0. Això generalment equival a dividir per 2^disp.

Tingueu en compte que un desplaçament per sobre de 31 donarà com a resultat 0.

bit32.arshift

bit32.arshift( n, disp )

Retorna el número n desplaçat disp bits a la dreta. Això és un desplaçament aritmètic: si disp és positiu, els bits inserits seran els mateixos que el bit 31 del número original.

Tingueu en compte que un desplaçament per sobre de 31 donarà lloc a 0 o 4294967295.

bit32.lrotate

bit32.lrotate( n, disp )

Retorna el número n havent rotat disp bits a l'esquerra.

Tingueu en compte que les rotacions són equivalents al mòdul 32: una rotació de 32 és el mateix que una rotació de 0, 33 és el mateix que 1, i així successivament.

bit32.rrotate

bit32.rrotate( n, disp )

Retorna el número n havent rotat disp bits a la dreta.

Tingueu en compte que les rotacions són equivalents al mòdul 32: una rotació de 32 és el mateix que una rotació de 0, 33 és el mateix que 1, i així successivament.

libraryUtil

Aquesta biblioteca conté mètodes útils per implementar biblioteques de Scribunto. Es pot carregar mitjançant:

 libraryUtil = require( 'libraryUtil' )

libraryUtil.checkType

libraryUtil.checkType( nom, argIdx, arg, expectType, nilOk )

Genera un error si type( arg ) no coincideix amb expectType. A més, no es generarà cap error si arg és nil i nilOk és true.

nom és el nom de la funció que fa la crida i argIdx és la posició de l'argument a la llista d'arguments. Aquests s'utilitzen per formatar el missatge d'error.

libraryUtil.checkTypeMulti

libraryUtil.checkTypeMulti( nom, argIdx, arg, expectTypes )

Genera un error si type( arg ) no coincideix amb cap de les cadenes de la matriu expectTypes.

Això és per a arguments que tenen més d'un tipus vàlid.

libraryUtil.checkTypeForIndex

libraryUtil.checkTypeForIndex( índex, valor, expectType )

Genera un error si type( value ) no coincideix amb expectType.

Això està pensat per a ser utilitzat en la implementació d'un metamètode __newindex.

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 new variable is used that is 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, which was replaced via phab:T209310. 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.

Biblioteques d'extensions

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:

• ScribuntoExternalLibraries
• ScribuntoExternalLibraryPaths

Writing Scribunto libraries provides information on how such libraries can be developed to provide Lua interfaces for MediaWiki extensions.

mw.wikibase

Wikibase Client provides access to localizable structured data, most notably Wikidata. See docs_topics_lua.html and Extension:Wikibase Client/Lua .

mw.wikibase.lexeme

WikibaseLexeme provides access to Wikibase Lexeme entities. This is supported by Wikidata:Lexicographical data. See docs_topics_lua.html and Extension:WikibaseLexeme/Lua .

mw.wikibase.mediainfo

WikibaseMediaInfo provides access to Wikibase MediaInfo entities. See WikibaseMediaInfo/Lua . This is supported by Structured Data on Commons. See 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 Scribunto support for the Semantic MediaWiki extension.

mw.ext.data

JsonConfig provides access to localizable tabular and map data. See JsonConfig/Tabular . Tabular Data and GeoJSON Map Data is supported in the "Data:" namespace at Commons.

• mw.ext.data.get( pagename )

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. It is experimental and not enabled on public Wikimedia wikis. But the "categories" field of the title object does the same work and is enabled.

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.translate.messageBundle

[EXPERIMENTAL] Part of the Translate extension. Provides a means to query translations present inside message bundles . Read module documentation for more information.

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:Extension:ProofreadPage .

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 the Internet from Lua. See Extension:External Data/Lua .

mw.ext.UnlinkedWikibase

See UnlinkedWikibase

• mw.ext.UnlinkedWikibase.getEntity( id )
• mw.ext.UnlinkedWikibase.query( sparql )

mw.ext.seo

WikiSEO provides a means to set SEO Data for the current page. See WikiSEO#Usage in lua modules.

mw.slots

WSSlots provides a number of Lua functions for working with MCR slots:

• mw.slots.slotContent(slotName, pageName)
• mw.slots.slotTemplates(slotName, pageName) (deprecated)
• mw.slots.slotContentModel(slotName, pageName)
• mw.slots.slotData(slotName, pageName)

mw.ext.tabber

TabberNeue provides a means to render a Tabber from Lua. See Extension:TabberNeue#Lua for usage.

Diferències respecte al Lua estàndard

Funcions canviades

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.

Funcions i paquets eliminats

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.

Advertències addicionals

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().

Escrivint biblioteques 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 MediaWiki\Extension\Scribunto\Engines\LuaCommon\LibraryBase. 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 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

    -- Indicate that we're loaded
    package.loaded['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.

Casos de prova

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 ''ClassName''Test extends Scribunto_LuaEngineTestBase {
     protected static $moduleName = '<i>ClassName</i>Test';
 
     function getTestModules() {
          return parent::getTestModules() + array(
              '<i>ClassName</i>Test' => __DIR__ . '/<i>ClassName</i>Tests.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().

Casos de prova en una altra extensió

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.
2. 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ó

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.

Vegeu també

• Lua (programming language)

• Unit testing (and debugging) of modules

Llicència

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