Extension:Scribunto/Manuel de référence Lua

Ce manuel documente Lua tel qu’il est utilisé sur MediaWiki avec l’extension Scribunto . Certaines parties sont issues du manuel de référence Lua 5.1, qui est disponible sous licence MIT.

Introduction

Pour commencer

Sur un wiki MediaWiki avec Scribunto activé, créer une page avec un titre commençant par Module:, par exemple « Module:Bananas ». Dans cette nouvelle page, copiez le texte suivant :

local p = {} --p est l’abrégé de paquet

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

return p

Enregistrer cela, puis sur une autre page (non-module), comme sur une page du bac à sable, écrire :

{{#invoke:Bananas|hello}}

Sauf que vous devriez remplacer « Bananas » par le nom que vous avez donné à votre module. Cela appellera la fonction « hello » exportée à partir de ce module. Le {{#invoke:Bananas|hello}} sera remplacé par le texte renvoyé par la fonction, dans ce cas, « Hello, world! »

C'est généralement une bonne idée que d'invoquer un code Lua depuis le contexte d'un modèle. Cela signifie que vu d'une page appelante, la syntaxe est la même, que la logique du modèle soit écrite en Lua ou en wikicode. Cela évite aussi d'introduire en plus une syntaxe complexe dans l'espace de noms du contenu d'un wiki.

Structure d'un module

Le module lui-même doit renvoyer une table Lua contenant des fonctions qui peuvent être appelées via {{#invoke:}}. Généralement, comme cela a été montré ci-dessus, une variable locale est déclarée associée à une table, des fonctions sont ajoutées dans cette table, et cette dernière est renvoyée à la fin du code du module.

Toute fonction qui n'est pas ajoutée à cette table, qu'elle soit locale ou globale, ne sera pas accessible via {{#invoke:}}, mais les fonctions globales resteront accessibles depuis les autres modules chargés via la fonction require(). Il est généralement de bon ton dans un module de déclarer toutes les fonctions et les variables avec le mot-clé local.

Accès aux paramètres depuis le wikicode

Les fonctions appelées par {{#invoke:}} reçoivent un seul paramètre : un objet frame. Pour accéder aux paramètres passés à {{#invoke:}}, le code utilisera typiquement la table args de cet objet frame. Il est aussi possible d'accéder aux paramètres transmis au modèle contenant le {{#invoke:}} en utilisant frame:getParent() pour accéder à la table args de ce frame.

Cet objet frame est aussi utilisé pour accéder aux fonctionnalités spécifiques du contexte pour les analyseurs de wikicode, telles que l'appel des fonctions d'analyseur, le développement des modèles, et l'expansion arbitraire des chaînes de wikicode.

Renvoyer du texte

La fonction du module doit normalement renvoyer une chaîne. Quelles que soient les valeurs renvoyées, celles-ci passeront par tostring() et les résultats seront concaténés sans séparateur. Cette chaine résultante est incorporée dans le wikitexte comme résultat de {{#invoke:}}.

À ce stade de l’analyse de la page, les modèles ont déjà été développés, les fonctions d’analyseur et les balises d’extension ont déjà été traitées, et les transformations de pré-enregistrement (comme l'expansion de la signature avec des tilde ~~~~ et la barre verticale) ont déjà eu lieu. Par conséquent, le module ne peut pas utiliser ces fonctionnalités dans son texte de sortie. Par exemple, si un module retourne "Hello, [[world]]! {{welcome}}", la page affichera « Hello, world! {{welcome}} ».

D'autre part, subst est géré plus tôt dans le traitement d'une page, donc avec {{subst:#invoke:}} seules les autres tentatives de substitution seront évaluées. Comme les substitutions qui ont échoué vont rester dans le wikicode elle seront ensuite traitées lors de la prochaine modification. Cette situation doit être évitée.

Documentation d'un module

Scribunto permet de documenter un module en lui associant automatiquement une page wikicode de documentation; par défaut on utilise la sous-page "/doc" du module, et son contenu est inclus avant le code source du module. Par exemple la documentation de "Module:Bananas" sera dans "Module:Bananas/doc".

Ceci peut se configurer en utilisant les messages système suivants :

• scribunto-doc-page-name — Définit le nom de la page contenant la documentation. Le nom du module (sans le préfixe « Module: ») est transmis dans $1. Si ces pages sont dans l'espace de noms des modules elles sont traitées comme étant du wikitexte et non comme du code source Lua et ne doivent donc pas être utilisées avec {{#invoke:}}. La valeur par défaut est « Module:$1/doc », c’est-à-dire la sous-page /doc du module. Notez que les fonctions parseurs et les autres expansions des accolades ne peuvent pas être utilisées dans ce message.
• scribunto-doc-page-does-not-exist — Message affiché lorsque la page de documentation n’existe pas. Le nom de la page est passé comme $1. Vide par défaut.
• scribunto-doc-page-show — Message affiché lorsque la page de documentation existe réellement. Le nom de la page est passé dans $1. Par défaut, c'est la page de documentation qui est transcluse.
• scribunto-doc-page-header — entête affiché quand la page de documentation est elle-même visionnée. Le nom du module (préfixé par Module:) qu’elle documente est passé dans $1. Par défaut, une simple explication est affichée en italique.

Notez que les modules ne peuvent pas être directement catégorisés, ni avoir de liens interwikis directement ajoutés. La catégorisation peut se faire dans la documentation à l'intérieur des balises ‎<includeonly>...‎</includeonly>. Elle ne sera ainsi appliquée qu'au module lorsque la page de documentation sera transcluse dans la page du module.

Renommer ou déplacer des modules

Pour renommer ou déplacer un module, utilisez le lien Renommer dans le menu Outils de la barre latérale. Il faut probablement déplacer la sous-page de documentation avec le module.

Pour créer manuellement une redirection de module, utilisez la syntaxe suivante :

return require [[Module:Foo]]

Remplacez Foo par le nom du module vers lequel vous voulez rediriger.

Langage Lua

Entités

Les noms (aussi appelés identifiants) dans Lua peuvent être n'importe quelle chaîne de lettres, chiffres et caractères souligné (_) et ne pas commencer par un chiffre. Les noms sont sensibles à la casse : "foo", "Foo" et "FOO" sont trois noms distincts.

Les mots-clés suivants sont réservés et ne peuvent servir de nom :

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

Les noms commençant par un caractère souligné '_' et suivi de lettres en majuscules sont réservés pour les variables globales internes de Lua (exemple : _VERSION).

Les autres séquences de caractères sont :

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

Commentaires

Un commentaire commence par -- n'importe où, en dehors d'une chaîne. Si -- est immédiatement suivi par un crochet long ouvrant le commentaire se termine au crochet long fermant correspondant, sinon le commentaire se termine à la fin de la ligne où il a commencé.

-- Un commentaire en Lua commence avec un double-tiret et se termine à la fin de la ligne
--[[ Les chaînes et les commentaires multi-lignes 
  son entourés de double crochets. ]]
--[=[ Des commentaires comme celui-ci peuvent contenir --[[d'autres commentaires]] imbriqués. ]=]
--[==[ Des commentaires de cette sorte contiennent 
      --[===[ de longs --[=[commentaires]=] --imbriqués
        ]===] plusieurs fois, même si chacun d'entre eux n'est pas
      --[[ borné par des crochets longs appairés! ]===]
  ]==]

Types de données

Lua est un langage typé dynamiquement. Cela signifie que les variables et les arguments des fonctions n’ont pas de type, seulement des valeurs qui leur sont assignés. Chaque valeur par contre possède un type.

Lua possède huit types basiques de données, toutefois seuls six sont utilisables dans l’extension Scribunto. La fonction type() renvoie le type d'une valeur qu'on lui a fournie.

La fonction tostring() convertit une valeur en chaîne. La fonction tonumber() convertit une valeur en nombre quand c’est possible, sinon elle renvoie la valeur nil. Il n’y a pas d’autres fonctions explicites pour convertir une valeur vers tout autre type.

Les nombres sont automatiquement convertis en chaînes quand ils sont utilisés là où une chaîne est attendue (par exemple avec l'opérateur de concaténation). Les chaînes reconnues par tonumber() sont automatiquement converties en nombres quand elles sont utilisées avec des opérateurs arithmétiques. Quand une valeur booléenne est attendue toute valeur différente de nil ou false est considérée comme valant true.

néant (nil)

" nil" est le type de données nil, qui existe pour représenter l’absence d’une valeur.

nil ne peut pas être utilisé comme clé dans une table et il n’y a aucune différence entre une clé de table non assignée et une clé assignée à la valeur nil.

Lorsqu’il est converti en une chaîne, le résultat est "nil". Lorsqu’il est converti en booléen, nil est considéré comme faux.

Remarque : Lua fait une distinction entre nil et rien du tout dans certaines situations limitées. Par exemple, tostring(nil) renvoie "nil", mais tostring() renvoie une erreur, car le premier paramètre est requis. Cette distinction est particulièrement pertinente pour la fonction select().

booléen (boolean)

Les valeurs que peut prendre un booléen sont true ou false.

La conversion d'un booléen en chaine donne "true" ou "false".

Contrairement à d'autres langages, les booléens ne peuvent être convertis directement en nombres. Et contrairement à d'autres langages, seuls false et nil sont assimilés à false dans la conversion booléenne; le nombre 0 et la chaine vide (="" ou ='') sont tous deux considérés comme "true".

chaîne (string)

Les chaînes en Lua sont considérées comme des séries d'octets (8 bits), et c'est à l'application de les interpréter au besoin dans un encodage particulier.

Les chaînes littérales peuvent être délimitées par des apostrophes ou des guillemets verticaux (' ou "). Comme en JavaScript mais contrairement à PHP, il n’y a aucune différence entre ces deux notations. Les séquences d’échappement suivantes sont reconnues :

• \a (bell, caractère d’appel, octet 7)
• \b (backspace, espacement arrière, octet 8)
• \t (horizontal tab, tabulation horizontale, octet 9)
• \n (newline, saut de ligne, octet 10)
• \v (vertical tab, tabulation verticale, octet 11)
• \f (form feed, saut de page, octet 12)
• \r (carriage return, retour à la ligne, octet 13)
• \" (double quote, guillemets verticaux, octet 34)
• \' (single quote, apostrophe verticale, octet 39)
• \\ (backslash, barre oblique inversée, octet 92)

Un retour à la ligne littéral peut aussi être inclus en le précédant d’une barre oblique inverse (\). Les octets peuvent aussi être donnés en utilisant la séquence d'échappement '\ddd', où ddd est la valeur décimale de l'octet (entier entre 000 et 255). Pour inclure des caractères Unicode en utilisant des séquences d'échappement, chaque octet de son codage UTF-8 doit être spécifié. En général il est nettement plus simple de saisir directement les caractères Unicode directement.

Une chaîne constante peut aussi être définie en utilisant des crochets longs. Un crochet long ouvrant est un crochet ouvrant suivi éventuellement de zero ou plusieurs signes « égal » ("=") et suivi d'un autre crochet ouvrant. Exemples : [[, [=[ ou [=====[. Un crochet long ouvrant doit être associé à un crochet long fermant. Exemples : ]], ]=] ou ]=====].. Il existe un cas particulier : si un retour à la ligne est présent juste après un crochet long ouvrant, alors ce retour à la ligne n'est pas intégré à la chaîne ; par contre, si un retour à la ligne est mis juste avant le crochet long fermant, il est conservé. Les chaînes délimitées par des crochets longs n’interprètent pas les séquences d’échappement.

-- Cette longue chaine :
foo = [[
bar\tbaz
]]

-- est équivalente à celle-ci délimitée par des apostrophes :
foo = 'bar\\tbaz\n'

Notez que contrairement à la plupart des autres langages, toute chaîne est considérée comme vraie quand elle est convertie en booléen, même la chaîne vide.

nombre (number)

Lua n’a qu’un seul type numérique, qui est généralement représenté en interne sous la forme d’une valeur à virgule flottante double précision 64 bits. Dans ce format, les entiers compris entre -9007199254740991 (-2⁵³ + 1) et 9007199254740991 (2⁵³ - 1) peuvent être représentés exactement ; Les nombres plus grands et les nombres avec une partie fractionnaire peuvent souffrir d’une erreur d’arrondi.

Les constantes numériques sont notées avec un point (.) comme séparateur décimal et sans séparateur de groupe (exemple : 123456.78). Les nombres peuvent aussi utiliser la notation E avec exposant et sans espace (exemples : 1.23e-10, 123.45e20 ou 1.23E+5). Les entiers peuvent également être spécifiés en notation hexadécimale en utilisant le préfixe 0x, par exemple 0x3A.

Une poignée de valeurs numériques sont gérées d’une manière particulière :

• L’infini positif et l’infini négatif, qui s’élèvent respectivement à être supérieurs ou inférieurs à tous les autres nombres (sauf les NaNs - voir ci-dessous). Ceux-ci peuvent être accessibles de deux manières : via la bibliothèque math, comme math.huge et -math.huge, ou par des opérations numériques telles que 1/0 et -1/0.
• Lua distingue occasionnellement 0 et -0 (voir le IEEE 754 pour plus d’informations sur les zéros signés). 0 et -0 sont strictement équivalents à presque toutes les fins, mais se comportent différemment dans un petit nombre d’opérations numériques (par exemple, 1/0 renvoie l’infini, tandis que 1/-0 renvoie l’infini négatif). La distinction affecte également les conversions de nombre en chaîne (et vice-versa).
• Positif et négatif NaN (pour Pas un numéro). Aucune constante n’est fournie pour l’un ou l’autre de ces éléments, mais 0/0 est évalué à NaN négatif. Notez que les deux NaN ont la qualité unique que toute comparaison qui les implique évalue à false (ce qui signifie qu’ils ne s’évaluent même pas comme étant égaux à eux-mêmes). La seule distinction pratique entre les deux concerne la conversion de type en chaîne et à partir de chaîne (voir ci-dessous).

Notez que tous les nombres (y compris 0, -0, les infinis et les NaN) sont considérés comme vrais lorsqu’ils sont convertis en booléens. Contrairement à la plupart des autres langages, où 0 est généralement considéré comme faux. Lorsqu’ils sont convertis en chaîne de caractères, les nombres finis sont représentés en décimal, et la notation E si 10¹⁴ ou plus (par exemple, "1e+14") ; les infinis sont "inf" et "-inf" ; et les NaN sont "nan" et "-nan".

Bug connu : l’interpréteur traite toutes les instances de 0 et -0 comme l’un des deux selon celui qui est rencontré en premier quand le code est compilé, ce qui implique que les valeurs de retour de tostring(0), 1/-0 et autres sont affectées quand elles sont dans le code. Cela peut entraîner des résultats inattendus, en particulier si toutes les instances de 0 sont converties en "-0". Si nécessaire, cela peut être contourné en générant des valeurs zéro à l'aide de tonumber("0") et tonumber("-0"), ce qui ne semble pas causer ou être affecté par le problème. Voir [1].

table

Les tables Lua sont des tableaux associatifs, similaires aux tableaux PHP et aux objets JavaScript.

Les tables sont créées avec les accolades. La table vide est {}. Pour remplir les champs de la une table à la création, une liste d'éléments séparés par des virgules et/ou des point-virgules peut être insérée entre les accolades. Chaque élément peut prendre l'un des formats suivants :

• * [expression1] = expression2 utilise la (première) valeur de expression1 comme la clé et la (première) valeur de [expression1] = expression2 comme la valeur.
• $4 est équivalent à $5
• $6 est à peu près équivalent à $7, où $8 est un entier valant 1 au départ et incrémenté de 1 après chaque ajout de cette forme.

Si le dernier élément spécifié est une expression renvoyant plusieurs valeurs, toutes ces valeurs sont utilisées ; dans tous les autres cas seule la première valeur renvoyée l'est.

• name = expression is equivalent to ["name"] = expression
• expression is roughly equivalent to [i] = expression, where i is an integer starting at 1 and incrementing with each field specification of this form. If this is the last field specifier and the expression has multiple values, all values are used; otherwise only the first is kept.

Les champs d'une table sont accessibles en utilisant la notation entre crochets, par ex. table[key]. Les clés de chaîne qui sont également des noms valides peuvent également être accédées en utilisant la notation par points, par ex. table.key équivaut à table['key']. L'appel d'une fonction qui est une valeur dans la table peut utiliser la notation deux-points; par exemple, table:func( ... ), ce qui équivaut à table['func']( table, ... ) ou table.func( table, ... ).

Un tableau (aussi appelé séquence ou liste) est une table avec des valeurs non nulles pour tous les entiers positifs de 1 à N et aucune valeur (nil) pour tous les entiers positifs supérieurs à N. De nombreuses fonctions Lua fonctionnent uniquement sur des tableaux et ignorent les clés entières non positives.

Contrairement à d'autres langages tels que PHP ou JavaScript, toute valeur en dehors de nil et de NaN peuvent être utilisées comme clé et aucun type de conversion n'est effectué. Les entrées ci-dessous sont toutes valides et distinctes :

-- Création de la table
t = {}
t["foo"] = "foo"
t.bar = "bar"
t[1] = "un"
t[2] = "deux"
t[3] = "trois"
t[12] = "le nombre douze"
t["12"] = "la chaîne douze"
t[true] = "true"
t[tonumber] = "oui, même les fonctions peuvent être les clés de tableaux"
t[t] = "oui, une table peut être aussi une clé de table. Même pour elle-même."

-- Ceci crée une table globalement équivalente à la précédente
t2 = {
    foo = "foo",
    bar = "bar",
    "un",
    "deux",
    [12] = "le nombre douze",
    ["12"] = "la chaîne douze",
    "trois",
    [true] = "true",
    [tonumber] = "oui, même les fonctions peuvent être des clés de table",
}
t2[t2] = "oui, une table peut être aussi la clé d'une autre table. Même pour elle-même."

De la même façon, n'importe quelle valeur peut être utilisée comme valeur dans une table, à part nil. Stocker nil revient à effacer la clé de la table, et accéder à une clé qui n'a jamais reçu de valeur retourne nil.

Notez que les tables ne sont jamais copiées implicitement en Lua. Une table passée en paramètre à une fonction est passée par référence, si la fonction modifie le contenu de la table les changements seront visibles ensuite pour l'appelant.

Quand une table est convertie en chaîne, le résultat habituel est "table" mais ceci peut être modifié en utilisant la méta-méthode __tostring. Même une table vide est considérée comme un boléen true.

fonction (function)

En Lua les fonctions sont des objets de première classe : elles peuvent être créées « anonymement », être passées en paramètre, assignées à des variables, etc.

Les fonctions sont créées grâce au mot-clé function et appelées en utilisant les parenthèses. Un sucre syntaxique est disponible pour les fonctions nommées, les fonctions locales et les fonctions qui agissent comme des fonctions membres d'une table. Voir Déclarations de fonctions et Appels de fonctions plus loin pour plus de détail.

Les fonctions en Lua sont des fermetures, ce qui signifie qu'elles maintiennent une référence à l'environnement où elles ont été déclarées et peuvent manipuler les variables de cet environnement.

Comme pour les tables, les fonctions sont toujours manipulées "par référence", y compris lorsqu'elles sont stockées dans des variables ou transmises en paramètre à une autre fonction.

La conversion en chaine d'une "fonction" a pour résultat une "function".

Types non pris en charge

Le type userdata permet de stocker des données "opaques" pour les extensions de Lua écrites dans d'autres langages. Par exemple un "userdata" peut contenir un pointeur ou une structure C. Ceci n'est pas utilisé en Scribunto hébergé où le code non natif n'est pas autorisé.

Le type thread représente les références des co-routines, et ne sont pas disponibles dans le bac à sable de Scribunto.

return p

There is a strict limit of max 60 unique upvalues acessed inside a function. An upvalue is a value declared outside of a function and used inside it. As upvalues do count:

• variables (a table with many elements counts as one upvalue)
• functions (only those directly called from function in question, not their dependencies)

A violation of the limit can be triggered by a use of such a variable or function, not by its mere presence or availability. Repeated access to same upvalue does not exhaust the limit further.

Méta-tables

Chaque table peut avoir une table associée appelée méta-table. Les champs de la méta-table sont utilisés par certains opérateurs et fonctions pour permettre un comportement différent du comportement par défaut pour la table. La méta-table d'une table peut être accédée en utilisant la fonction getmetatable(), et modifiée avec la fonction setmetatable().

Quand ils sont accédés pour leurs méta-fonctions, les champs méta-tables sont accédés avec rawget().

Les champs d'une méta-table qui impactent la table elle-même sont :

__index

C'est utilisé quand l'accès à une table $1 aurait renvoyé nil. Si la valeur de ce champ est une table, l'accès sera tenté de nouveau dans cette table (par exemple $1, qui pourra à son tour appeler le __index de cette méta-table). Si la valeur de ce champ est une fonction, celle-ci est appelée ainsi : $1. La fonction rawget() court-circuite cette méta-méthode.

__newindex

C'est utilisé lorsqu'une valeur est assignée à une clé de la table et qu'il n'y a pas de valeur pour cette clé ($2 avec rawget( t, key ) renvoyant nil). Si la valeur de ce champ est une table, l'affectation sera faite sur cette table à la place, par exemple $1 (pourra éventuellement invoquer le __newindex de cette métatable). Si la valeur de ce champ est une fonction celle-ci est appelée comme suit : $1. La fonction rawset() court-circuite cette méta-méthode.

__call

Ceci est utilisé quand la syntaxe de l'appel de fonction est utilisé sur une table, $1. La valeur doit être une fonction, qui est appelée à la manière de : __call( t, ··· ).

__mode

Ceci est utilisé pour que les tables puissent contenir des « références faibles » (weak references). La valeur doit être une chaîne de caractères. Par défaut, toute valeur utilisée comme clé ou comme valeur dans une table ne sera pas nettoyée par le ramasse-miettes (garbage collector). Mais si ce méta-champ contient la lettre 'k' les clés peuvent être nettoyées s'il n'y a pas de mauvaises références, et s'il contient la lettre 'v' ses valeurs peuvent être « nettoyées »; dans les deux cas, la clé et la valeur correspondante seront effacées de la table. Notez que le comportement est indéterminé si ce champ est modifié après que la table soit utilisée en tant que méta-table.

Les autres champs de méta-tables sont :

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

^† Pour les opérateurs binaires, Lua regarde d'abord la méta-table du paramètre de gauche (s'il y en a une), puis celle du paramètre de droite quand il cherche quelle méta-méthode utiliser.

^‡ Pour les opérateurs relationnels, la méta-méthode est utilisée uniquement si la même fonction est donnée pour les deux paramètres dans leurs méta-tables respectives. Des fonctions anonymes, même avec un contenu identique et la même fermeture, ne peuvent pas être considérées comme identiques.

^* __metatable affecte à la fois getmetatable() et setmetatable().

Note : en Lua, toutes les chaînes partagent une seule et même méta-table, dans laquelle __index fait référence à la table string. Cette méta-table n'est pas accessible en Scribunto, et la table référencée de string non plus; seule une copie de la table string est disponible dans les modules.

Variables

Les variables sont des endroits pour stocker des valeurs. Il y a trois sortes de variables en Lua : les variables globales, les variables locales et les champs de tables.

Un nom représente une variable globale ou locale (ou un paramètre de fonction, qui est une sorte de variable locale). Les variables sont supposées être globales (il n'existe pas de mot réservé pour global), à moins d'être explicitement déclarées comme locales en utilisant le mot-clé local. Toute variable à laquelle on n'a pas affecté de valeur contient la valeur nil.

Les variables globales sont stockées dans une table Lua standard appelée environment. Cette table est généralement disponible en tant que variable globale _G. Il est possible d'attacher une méta-table à cette table globale. Les méta-méthodes __index et __newindex seront respectivement appelées pour les accès et les affectations à des variables globales comme elles le seraient pour accéder et asdigner les champs de n'importe quelle autre table.

L'environnement d'une fonction peut être accédé en utilisant la fonction getfenv() et modifié en utilisant la fonction setfenv(). En Scribunto ces fonctions sont fortement restreintes voire inutilisables.

Les variables locales ont une portée lexicale; voir la Déclarations des variables locales pour les détails.

Expressions

Une expression est un morceau de code qui a une ou plusieurs valeurs. Sont des expressions : les littéraux (nombres, chaines, true, false, nil), les déclarations de fonctions anonymes, les constructeurs de tables, les références à des variables, les appels de fonctions, la liste variable d’arguments, les expressions entre parenthèses, les opérateurs unaires appliqués à des expressions, et les expressions combinées par des opérateurs binaires.

La plupart des expressions n’ont qu'une seule valeur. Les appels de fonctions et la liste variable d’arguments peuvent en renvoyer un nombre quelconque (y compris aucune). Notez que l’encadrement entre parenthèses d’un appel de fonction ou du symbole de la liste variable d’arguments (...) lui fait perdre toutes ses valeurs sauf la première.

Les listes d'expressions sont des listes d'expressions séparées par des virgules. Pour chacune de ces expressions sauf la dernière, seule la première valeur renvoyée sera prise en compte (en ignorant toutes les valeurs additionnelles, et en utilisant la valeur nil si l'expression n'a pas de valeur). Toutes les valeurs de la dernière expression sont incluses dans les valeurs de la liste d'expressions.

Opérateurs arithmétiques

Lua supporte les opérateurs arithmétiques habituels : addition, soustraction, multiplication, division, modulo (reste d'une division entière), exposant et négation.

Si tous les opérandes sont des nombres ou des chaines pour lesquelles tonumber() ne renvoie pas nil, les opérations ont leur fonctionnement habituel.

Si l'un des opérandes est une table avec une méta-méthode appropriée, cette méta-méthode sera appelée.

Opérateur	Fonction	Exemple	Méta-méthode associée	Notes
+	Addition	a + b	__add
-	Soustraction	a - b	__sub
*	Multiplication	a * b	__mul
/	Division	a / b	__div	La division par zéro n'est pas une erreur : si a est non nul, a/0 retournera une valeur infinie (voir math.huge) ou NaN (selon l'implémentation interne de la bibliothèque mathématique et sa représentation des nombres), sinon 0/0 retournera une valeur NaN.
%	Modulo	a % b	__mod	défini comme a % b == a - math.floor( a / b ) * b
^	Exposant	a ^ b	__pow	les valeurs non entières des exposants sont autorisées
-	Négation	-a	__unm

Opérateurs relationnels

En Lua, les opérateurs de relation sont ==, ~=, <, >, <= et >=. Le résultat d'un opérateur relationnel est toujours un booléen.

L'égalité (==) compare d'abord le type de ses opérandes. S'ils sont différents le résultat est faux. Ensuite il compare leur valeur : nil, booléen, nombre et chaines sont comparées de la façon usuelle. Les fonctions sont égales si elles font référence au même objet exactement (function() end == function() end retournera faux car il s'agit de la comparaison de deux fonctions anonymes différentes). Les tables sont comparées de la même façon mais ceci peut être modifié en utilisant la méta-méthode __eq.

La différence — ou inégalité — (~=) est la négation exacte de l'égalité.

Pour les opérateurs d'ordre, si les deux opérandes sont des nombres ou des chaines ils sont comparés directement. Ensuite la présence de méta-méthodes est vérifiée :

• a < b utilise __lt
• a <= b utilise __le s’il est disponible, ou si __lt est disponible, il est considéré comme équivalent à not ( b < a )
• a > b est considéré comme équivalent à b < a
• a >= b est considéré comme équivalent à b <= a

Si aucune méta-méthode n'est trouvée, une erreur est générée.

Opérateurs logiques

Les opérateurs logiques sont and, or et not. Tous utilisent l’interprétation standard où zéro et faux sont considérés comme faux et tout le reste est considéré comme vrai.

Pour and, si l’opérande gauche est considéré comme faux, il est renvoyé et le deuxième opérande n’est pas évalué ; sinon, le deuxième opérande est retourné.

Pour or, si l’opérande gauche est considéré comme vrai, il est renvoyé et le deuxième opérande n’est pas évalué ; sinon, le deuxième opérande est retourné.

Pour or, si l'opérande de gauche est vrai alors il est renvoyé et l'opérande de droite n'est pas évalué ; sinon l'opérande de droite est renvoyé.

Pour not, le résultat est toujours true ou false.

Notez que les courts-circuits à 1 $ et 2 $. Par exemple, foo() or bar() n’appellera bar() que si foo() renvoie false ou nil comme première valeur.

Opérateur de concaténation

L’opérateur de concaténation est composé de deux points, utilisé comme a .. b. Si les deux opérandes sont des nombres ou des chaînes, ils sont convertis en chaînes et concaténés. Sinon, si une métaméthode de __concat est disponible, elle est utilisée. Dans le cas contraire, une erreur est générée.

Notez que les chaines en Lua sont non modifiables et que Lua ne donne aucune moyen d'en construire, donc une boucle qui fait a = a .. b aura à créer une nouvelle chaine à chaque itération et éventuellement le nettoyage mémoire s'occupera des chaines inutilisées. Si de nombreuses chaines doivent être concaténées, il peut être plus rapide d'utiliser string.format() ou d'insérer les chaines dans une séquence et d'utiliser table.concat() ensuite.

Opérateur de longueur

L’opérateur de longueur est #, utilisé comme #a. Si a est une chaîne, il renvoie la longueur en octets. Si a est une table séquence, il renvoie la longueur de la séquence.

Si a est une table qui n’est pas une séquence, #a peut renvoyer 0 ou n’importe quelle valeur N telle que aa[N] n’est pas zéro et aa[N+1] est nul, même s’il y a des valeurs non nulles aux indices supérieurs. Par exemple

-- Ce n'est pas une séquence, car aa[3] est ''nil'' et aa[4] ne l'est pas.
a = { 1, 2, nil, 4 }

-- Ce qui suit peut alors renvoyer soit 2 soit 4,
-- et ça peut changer même si la table n'est pas modifiée :
mw.log( #a )

Précédence des opérateurs

Voici la précédence des opérateurs, de la plus haute priorité à la plus basse :

1. ^
2. not # - (négation numérique)
3. * / %
4. + - (soustraction)
5. ..
6. < > <= >= ~= ==
7. and
8. or

Pour un niveau de précédence donné, la plupart des opérateurs binaires sont associatifs à gauche. Par exemple, a / b / c est interprété comme (a / b) / c.

L'exposant et la concaténation sont en revanche associatifs à droite. Par exemple, a ^ b ^ c est interprété comme a ^ (b ^ c).

Appels de fonctions

Les appels de fonctions en Lua sont similaires à ceux dans la plupart des autres langages : un nom suivi d'une liste de paramètres entre parenthèses :

fonc( liste-d’expressions )

Comme pour toutes les listes d'expressions en Lua, la dernière expression de la liste peut fournir plusieurs valeurs d'argument.

Si une fonction est appelée avec moins de valeurs dans la liste-d’expressions que le nombre de paramètres définis dans la fonction, les paramètres additionnels auront la valeur nil. Si la liste-d’expressions contient plus de valeurs que la fonction n'a de paramètres définis, les valeurs en trop sont ignorées. Une fonction peut aussi avoir un nombre variable de paramètres. Voir Déclarations de fonctions.

Lua autorise également l'appel direct à la valeur retournée par une fonction (func()()). Si une expression plus complexe qu'un accès de variable est nécessaire pour déterminer quelle fonction doit être appelée, une expression entre parenthèses pourra être utilisée.

Lua possède des raccourcis pour deux cas fréquents. Le premier cas est celui où une table est utilisée comme un objet, et que la fonction est à appeler comme une méthode de cet objet. La syntaxe :

table:nom( liste-d’expressions )

est strictement équivalente à :

table.nom( table, liste-d’expressions )

Le second cas est la façon dont Lua met en œuvre les paramètres nommés, en passant comme seul argument positionnel une table contenant une liste de correspondances de noms vers valeurs. Dans ce cas, les parenthèses autour de la liste des arguments sont optionnelles. Ceci fonctionne aussi si la fonction ne reçoit qu'une chaîne constante. Par exemple, les appels :

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

sont équivalents à :

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

Cela peut être combiné. Les appels suivants sont équivalents :

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

Déclarations de fonctions

La syntaxe pour déclarer une fonction est :

function nameoptional ( var-listoptional )
    bloc
end

Toutes les variables dans liste-de-variables sont locales à la fonction, et ont comme valeurs celles passées lors de l'appel à la fonction. Les variables locales additionnelles peuvent être déclarées dans le bloc.

Quand la fonction est appelée, les instructions dans block sont exécutées après la création et l'assignation des variables locales correspondant à var-list. Si une instruction return est atteinte, le bloc se termine et les valeurs de l'expression correspondant à l'appel de la fonction sont celles passées à l'instruction return. Si l'exécution atteint la fin du bloc de la fonction sans rencontrer de return, celle-ci n'aura aucune valeur.

Les fonctions en Lua sont à fermeture lexicale. Une habitude courante est de déclarer des variables « privées statiques » locales à la portée où la fonction est déclarée. Par exemple :

-- Ceci renvoie une fonction qui ajoute un nombre à son paramètre
function makeAdder( n )
    return function( x )
        -- La variable n du bloc extérieur est disponible ici pour être ajoutée à x
        return x + n
    end
end

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

Une fonction peut être déclarée pour accepter un nombre variable d'arguments en indiquant ... comme élément final dans var-list :

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

À l'intérieur du bloc de la fonction, l’expression ... peut être utilisée pour désigner la liste variable d’arguments, c’est-à-dire toutes les valeurs dans l'appel de la fonction qui sont fournies en plus des éventuels premiers paramètres nommés. Par exemple :

local join = function ( separator, ... )
    -- obtenir les arguments supplémentaires dans une nouvelle table
    local args = { ... }
    -- obtenir le nombre d'arguments supplémentaires, correctement
    local n = select( '#', ... )
    return table.concat( args, separator, 1, n )
end

join( ', ', 'foo', 'bar', 'baz' )
-- renvoie la chaîne "foo, bar, baz"

La fonction select() sert à traiter la liste variable d’arguments. En particulier, select( '#', ... ) doit être utilisée au lieu de #{ ... } pour compter le nombre de valeurs dans la liste variable d’arguments, car { ... } n'est pas forcément une séquence.

Lua fournit un raccourci syntaxique pour combiner la déclaration et l'assignation à une variable. Voir Déclaration de fonction comme instruction.

Notez que ceci ne marche pas :

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

Puisque la déclaration d'une fonction est traitée avant la fin de l'assignation des variables locales, "factorielle" dans le corps de la fonction fait référence à une variable globale de ce nom (probablement « vide » ou bien une autre fonction déjà existante). Ce problème peut être évité en déclarant la variable locale avant et en lui assignant sa valeur dans une instruction postérieure (exemple ci-dessous), ou en utilisant la syntaxe d'instruction de déclaration de fonctions.

Instructions

Une instruction est l'unité élémentaire d'exécution : une assignation, une structure de contrôle, un appel de fonction, une déclaration de variable, etc.

Un morceau (chunk en anglais) est une séquence d'instructions, éventuellement séparées par des point-virgules. Un morceau est considéré comme le corps d'une fonction anonyme, donc il peut déclarer des variables locales, recevoir des paramètres et renvoyer une valeur.

Un bloc (block) est aussi une séquence d'instructions comme un chunk. Un bloc peut être délimité pour créer une seule instruction : $1. Ceci peut être utilisé pour limiter la portée de variables locales ou pour ajouter un return ou un break au milieu d'un autre bloc.

Assignations

liste-de-variables = liste-d’expressions

La variable-list est une liste de variables séparées par des virgules. La expression-list est une liste de une ou plusieurs expressions, séparées par des virgules. Toutes les expressions sont évaluées avant que la première assignation ne soit effectuée, donc a, b = b, a va effectivement échanger les valeurs contenues dans a et b.

Déclaration locale de variables

local liste-de-variables

local liste-de-variables = liste-d’expressions

Des variables locales peuvent être déclarées n'importe où dans un bloc. La première forme (sans liste d’expressions) déclare l'existence des variables mais ne leur assigne pas de valeur − elles valent donc nil dans ce bloc. La seconde forme assigne des valeurs à ces variables en plus de les déclarer, comme décrit dans Assignations.

Notez que la visibilité d’une variable locale commence à l’endroit où elle est déclarée. Donc une déclaration telle que local x = x déclare une nouvelle variable locale nommée x et lui assigne la valeur de l'ancienne variable x visible dans la portée au dessus (qui devient alors invisible jusqu'à la fin de la portée courante). Une variable locale reste visible jusqu’à la fin du bloc où elle a été déclarée.

Structures de contrôle

while expr do bloc end

L'instruction while répète le bloc bloc tant que l'expression expr est vraie.

repeat bloc until expr

L'instruction repeat répète le bloc bloc jusqu'à ce que l'expression expr soit vraie. Les variables locales déclarées dans ce bloc peuvent être utilisées dans l'expression expr.

for nom = expr1, expr2, expr3 do bloc end
for nom = expr1, expr2 do bloc end

La première forme de boucle for déclare une variable locale et répète le bloc pour des valeurs de cette variable allant de expr1 à expr2 en ajoutant expr3 à chaque itération. Notez que expr3 peut être omise auquel cas la valeur 1 est utilisée ; cependant des valeurs non-numériques comme nil et false produisent une erreur. Toutes les expressions numériques sont évaluées une fois avant que la boucle ne démarre.

Cette forme de la boucle for est à peu près équivalente à :

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

mis à part que les variables var, limit et step ne sont pas accessibles. Notez que la variable name est locale au block. Pour utiliser sa valeur en dehors de la boucle, elle doit être copiée dans une variable déclarée en dehors de cette boucle.

for liste-de-variables in liste-d’expressions do bloc end

La seconde forme de la boucle for travaille avec une fonction itérateur. Comme dans la première forme, liste-d’expressions est évalué une fois avant le début de la boucle.

Cette forme de boucle for est à peu près équivalente à :

do
    local func, static, var = expression-list
    while true do
        local var-list = func( static, var )
        var = var1  -- ''var1'' est la 1ere variable de ''var-list''
        if var == nil then
            break
        end
        block
    end
end

mis à part une fois encore que les variables fonc, statique et variable ne sont pas accessibles. Notez que les variables variable1, variables-ignorées sont locales au bloc. Pour utiliser leurs valeurs en dehors de la boucle il faut les copier dans des variables déclarées en dehors de cette boucle.

La plupart du temps, liste-d’expressions est une unique fonction qui renvoie trois valeurs. Il est plus efficace d'avoir une fonction itérative qui ne dépend que des paramètres qu'on lui passe. Sinon Programming in Lua (en anglais) suggère d'utiliser une fermeture plutôt que de renvoyer une table en tant que variable statique et de mettre à jour ses membres à chaque itération.

if expr1 then bloc1 elseif expr2 then bloc2 else bloc3 end

Exécute bloc1 si expr1 renvoie vrai, sinon exécute bloc2 si expr2 renvoie vrai, et bloc3 sinon. La partie else block3 peut être omise, et la partie elseif exp2 then block2 peut être omise ou répétée autant que nécessaire.

return liste-d’expressions

L'instruction return est utilisée pour renvoyer une valeur dans une fonction ou un chunk (qui est une fonction). liste-d’expressions est une liste de zéro ou plus expressions séparées par des virgules.

Lua met en œuvre la Récursion terminale (tail calls) : si liste-d'expressions consiste uniquement en une expression qui est un appel de fonction, alors la pile courante de la fonction sera réutilisée pour l'appel à cette fonction. Ceci n'impacte que les fonctions qui manipulent la pile d'appel, comme getfenv() ou debug.traceback().

L'instruction return ne peut être qu'en dernière instruction d'un bloc. Si un return est nécessaire à un autre endroit, un bloc explicite (comme do return end) peut être utilisé.

break

L'instruction break est utilisée pour terminer l'exécution d'une boucle while, repeat ou for, sautant à l'instruction qui suit immédiatement la fin de la boucle.

L'instruction break ne peut être qu'en dernière instruction d'un bloc. Si un break est nécessaire à un autre endroit, un bloc explicite (comme do break end) peut être utilisé.

A la différence des autrees langages, Lua ne dispose pas d'instruction continue pour les boucles (c'est à dire d'une instruction permettant d'aller à l'itération suivante sans casser l'ensemble de la boucle). Il est assez simple de réaliser le même effet en imbriquant un bloc repeat ... until true immédiatement dans la boucle principale, qui ne s'exécutera toujours qu'une fois pour chaque itération de la boucle principale (parce que sa contition est toujours vraie). L'utilisation de break ne mettra fin qu'à la boucle la plus interne, et donc pratiquement la boucle principale passera à l'itération suivante. Si vous devez utiliser break dans la boucle principale, déclarez simplement une variable qui sera testée à chaque fois que que la boucle interne se termine, et initialisez-la lorsque c'est nécessaire.

Appel de fonction comme instruction

Une fonction peut être appelée et utilisée comme une instruction (sans affectation du retour). Dans ce cas, l'instruction est utilisée uniquement pour ses effets de bord (par exemple mw.log() qui enregistre des messages) et les valeurs retournées éventuelles sont ignorées.

Instruction de déclaration de fonctions

Lua fournit un raccourci syntaxique pour déclarer une fonction et l'assigner à une variable. Les paires de déclarations suivantes sont équivalentes :

-- Déclaration de base
function func( var-list ) bloc end
func = function ( var-list ) bloc end

-- Fonction locale
local function func( var-list ) bloc end
local func; func = function ( var-list ) bloc end

-- Fonction en tant que champ d'un tableau
function table.func( var-list ) bloc end
table.func = function ( var-list ) bloc end

-- Fonction en tant que méthode dans un tableau
function table:func( var-list ) bloc end
table.func = function ( self, var-list ) bloc end

Notez que la notation avec les deux-points est ici parallèle à la notation avec les deux-points pour les appels de fonction, en ajoutant un argument implicite nommé self au début de la liste des arguments.

Gestion des erreurs

Les erreurs peuvent être générées en utilisant les fonctions error() et assert(). Pour intercepter les erreurs, utilisez pcall() ou xpcall(). Notez que certaines erreurs internes à Scribunto ne peuvent pas être interceptées depuis un code Lua.

Nettoyage de la mémoire (garbage collection)

Lua gère automatiquement la mémoire. Ceci signifie que vous n'avez pas à vous préoccuper d'allouer de la mémoire pour de nouveaux objets ni de libérer cette mémoire quand les objets ne sont plus utilisés. Lua gère ceci exécutant un « nettoyeur de mémoire » (ou « ramasse-miettes ») de temps en temps pour supprimer les objets morts (les objets qui ne sont plus accessibles depuis Lua) et ceux qui sont accessibles uniquement depuis des références faibles. Toute la mémoire utilisée par Lua est gérée par le nettoyeur automatique : les tables, les fonctions, les chaînes, etc.

Le nettoyage de la mémoire est géré automatiquement et ne peut être configuré depuis Scribunto.

Bibliothèques standards

Les bibliothèques standards Lua fournissent divers services essentiels ainsi que des fonctions dotés d'une performance remarquable. Seules les parties des bibliothèques standards Lua disponibles en Scribunto sont décrites ici.

Fonctions de base

_G

Cette variable contient une référence vers la table des variables globales. La variable globale quelconque peut aussi être accédée avec _G.quelconque. Notez toutefois que _G n'a rien de spécial. En particulier, il est possible de changer sa valeur comme toute autre variable :

foo = 1
mw.log( foo ) -- journalise « 1 »
_G.foo = 2
mw.log( foo ) -- journalise « 2 »
_G = {}       -- _G ne pointe plus sur la variable tableau globale
_G.foo = 3
mw.log( foo ) -- journalise encore « 2 »

La table des variables globales peut être utilisée comme n'importe quelle autre table. Par exemple :

-- Appeler une fonction dont le nom est rangé dans une variable
_G[var]()

-- Journaliser les noms et les valeurs sous forme de chaîne de toutes les variables globales
for k, v in pairs( _G ) do
   mw.log( k, v )
end

-- Journaliser la création des nouvelles variables globales
setmetatable( _G, {
    __newindex = function ( t, k, v )
         mw.log( "Creation of new global variable '" .. k .. "'" )
         rawset( t, k, v )
    end
} )

_VERSION

Une chaîne qui contient la version de Lua en cours d'exécution (exemple : "Lua 5.1").

assert

assert( v, message, ... )

Si vérité vaut nil ou false, la fonction génère une erreur. Dans ce cas, message est utilisé comme texte du message d'erreur. Si message vaut nil ou n'est pas indiqué, il prendra la valeur par défaut la chaîne "assertion failed!" (en anglais). Si message est une chaîne ou un nombre, son contenu est utilisé, autrement assert lui-même génère une erreur.

Si v a toute autre valeur, assert() retourne tous ses paramètres y compris v et message.

Une approche courante en Lua est de faire des fonctions qui retournent true si tout se passe bien et en cas d'échec qui retournent nil ou false (comme première valeur) et un message d'erreur (comme seconde valeur). Une façon simple de gérer ces erreurs consiste à encadrer l'appel à la fonction dans un assert comme suit :

-- Ceci ne contrôle pas les erreurs
local result1, result2, etc = func( ... )

-- Ceci fonctionne de la même manière, mais contrôle effectivement les erreurs
local result1, result2, etc = assert( func( ... ) )

error

error( message, level )

Génère une erreur, avec comme texte d'erreur message.

error ajoute normalement des informations récursives sur l'endroit où l'erreur s'est produite, depuis la pile des appels de fonctions. Si level est 1 ou n'est pas précisé, cette information indique l'endroit où se trouve l'appel à error. Le niveau 2 indique l'endroit où s'est fait l'appel à la fonction qui a appelé error et ainsi de suite. Passer 0 supprime la transmission de ces informations.

getfenv

getfenv( f )

Notez que cette fonction peut ne pas être disponible en fonction de la valeur de allowEnvFuncs dans la configuration du moteur.

Renvoie un « environnement » (une table de variables globales) comme indiqué par f :

• Si f vaut 1, nil ou est omis, retourne l'environnement de la fonction qui appelle getfenv. La plupart du temps celui-ci est le même que celui indiqué par la variable globale _G, elle-même déclarée dans cet environnement et initialisée avec la valeur retournée par getfenv() (toutefois cette variable globale peut avoir été ensuite modifiée, ou avoir été supprimée de cet environnement en lui assignant la valeur nil ; on ne peut alors accéder à cet environnement initial qu'avec la fonction getfenv(), elle aussi présente dans l'environnement initial, à moins que la fonction ait été protégée).
• Un entier entre 2 et 10 retourne l'environnement des fonctions précédentes dans la pile d'appels. Par exemple 2 retourne l'environnement de la fonction qui a appelé la fonction courante et ainsi de suite. Une erreur est générée si cette valeur est plus grande que le nombre d'appels de fonctions dans la pile d'appels, ou si le niveau de pile correspond à un appel retourné dans une récursion terminale.
• Passer une fonction retourne l'environnement associé à cette fonction lorsqu'elle est appelée.

Les environnements utilisés par toutes les fonctions des bibliothèques standards et bibliothèques Scribunto sont protégés. Tenter d'y accéder avec getfenv renverra nil systématiquement.

getmetatable

getmetatable( table )

Renvoie la méta-table d'une table. Retourne nil si appelé sur une valeur d'un autre type que table.

Si la méta-table a un champ __metatable, cette valeur sera renvoyée au lieu de la vraie méta-table.

ipairs

ipairs( t )

Retourne trois valeurs : une fonction itérative, la table t, et 0. Cette fonction sert d'itérateur pour la forme itérative de la boucle for :

for i, v in ipairs( t ) do
    -- process each index-value pair
end

Ceci itérera sur les paires ( 1, t[1] ), ( 2, t[2] ), etc., s'arrêtant quand t[i] vaudra nil.

Le comportement standard peut être remplacé en fournissant une métaméthode __ipairs. Si cette métaméthode existe, l'appel à ipairs renverra les trois valeurs renvoyées par __ipairs( t ) à la place.

next

next( table, key )

Permet d'itérer sur les clés d'une table. Si key est nil ou absent retourne la « première » clé dans cette table ainsi que sa valeur. Sinon retourne la clé « suivante » et sa valeur. Retourne nil quand il n'y a plus de clés disponibles. Il est possible de tester si une table est vide en utilisant l'expression next( t ) == nil.

Notez que l'ordre dans lequel les clés sont retournées est non spécifié, même pour des tables ayant des index numériques. Pour traverser une table dans l'ordre numérique des clés, utilisez le for numérique ou ipairs.

Le comportement de next est non prévisible si, durant le parcours, on assigne une valeur à une nouvelle clé dans la table. Par contre assigner une valeur (y compris nil) à une clé existante ne pose pas de problème.

pairs

pairs( t )

Retourne trois valeurs : une fonction itérative (next ou quelque chose de similaire), la table t, et nil. Ceci a pour but d'être utilisé dans la forme itérative de la boucle for :

for k, v in pairs( t ) do
    -- traiter chaque paire clé-valeur
end

Ceci va itérer sur toutes les paires clé-valeur dans t, exactement comme next l'aurait fait. Voir next pour les limitations sur la modification de la table durant le parcours.

Ce comportement standard peut être évité en fournissant une méta-méthode __pairs. Si cette méta-méthode existe l'appel à pairs renverra les trois valeurs renvoyées par __pairs( t ) à la place.

pcall

pcall( f, ... )

Appelle la fonction f avec les paramètres indiqués en « mode protégé ». Ceci signifie que si une erreur se produit durant l'appel à f, pcall renverra false suivi du message d'erreur correspondant. Si aucune erreur ne se produit pcall renverra true suivi de toutes les valeurs renvoyées par l'appel.

Dans pseudocode, pcall pourrait ressembler à quelque chose comme :

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

rawequal

rawequal( a, b )

Ceci est équivalent à a == b sauf que cela ignore toute méta-méthode __eq .

rawget

rawget( table, k )

Ceci est équivalent à table[k] sauf que cela ignore toute méta-méthode __index.

rawset

rawset( table, k, v )

Ceci est équivalent à table[k] = v sauf que cela ignore toute méta-méthode __newindex .

select

select( index, ... )

Si index est un nombre, renvoie tous les arguments de ... à partir de cet index. Si index est la chaîne "#", renvoie le nombre d'arguments en ....

Note : au contraire des tables, les listes d'arguments (dont l'expression vararg ...) traitent nil comme une valeur séparée (voir la documentation pour # et unpack pour le problème avec nil dans des tables). Par exemple :

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

En d’autres termes, select est à peu près comme ce qui suit (sauf qu’il gère également tous les arguments nil après l’argument final non-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 )

Initialise la méta-table d'une table. metatable peut valoir nil mais doit être explicitement formulé.

Si la méta-table courante possède un champ __metatable, setmetatable génère une erreur.

tonumber

tonumber( value, base )

Tente de convertir value en nombre. Si c'est déjà un nombre ou une chaine convertible en nombre, alors tonumber renvoie ce nombre ; sinon il renvoie nil.

Le paramètre optionnel base (qui vaut 10 par défaut) permet de préciser la base pour interpréter le nombre. La base peut être un entier entre 2 et 36 inclus. Dans les bases au dessus de 10, la lettre 'A' (majuscule ou minuscule) représente 10, 'B' représente 11, et ainsi de suite jusqu'à 'Z' qui représente 35.

En base 10, les valeurs peuvent avoir une partie décimale, être exprimées en notation avec exposant (ex: 6.022E23). Le préfixe "0x" de la valeur indique la base 16 sans qu'il soit nécessaire de le spécifier. Dans les autres bases, seuls les entiers non signés sont acceptés.

tostring

tostring( value )

Permet de convertir value en chaîne. Voir Types de données ci-dessus pour les détails sur la manière dont chaque type est converti.

Le comportement standard pour les tables peut être évité en fournissant la méta-méthode __tostring. Si cette méta-méthode existe, l'appel à tostring renverra la seule valeur renvoyée par __tostring( value ) à la place.

type

type( value )

Renvoie le type de value dans une chaîne. Les résultats possibles sont : "nil", "number", "string", "boolean", "table" ou "function".

unpack

unpack( table, i, j )

Retourne les valeurs de la table indiquée d'une façon similaire à table[i], table[i+1], ···, table[j] si on devait l'écrire manuellement. Si nil ou non indiqué, i vaut par défaut 1 et j vaut par défaut #table.

If the table does not have a value for a particular key, unpack will return nil for that value. For example, unpack({"foo", [3] = "bar"}, 1, 4) returns "foo", nil, "bar", nil.

Notez que le résultat est non déterministe si table n'est pas une séquence et j est nil ou non précisé. Voir Opérateur de longueur pour plus de détails.

xpcall

xpcall( f, errhandler )

Cette fonction est similaire à pcall mis à part que le message d'erreur est passé à la fonction errhandler avant d'être renvoyé.

Dans pseudocode, xpcall pourrait ressembler à quelque chose comme :

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

Bibliothèque de débogage

debug.traceback

debug.traceback( message, level )

Retourne une chaine contenant une trace de la pile d'appel. Un message optionnel est ajouté au début de la chaine retournée si fournie. Un niveau de profondeur (level) optionnel permet de préciser à quelle profondeur commencer le retour de la pile d'appel.

Bibliothèque mathématique

math.abs

math.abs( x )

Renvoie la valeur absolue de x.

math.acos

math.acos( x )

Renvoie l'arc cosinus de x (en radians).

math.asin

math.asin( x )

Renvoie l'arc sinus de x (en radians).

math.atan

math.atan( x )

Renvoie l'arc tangente de x (en radians).

math.atan2

math.atan2( y, x )

Retourne l'arc tangente de y/x (en radians), en utilisant le signe des deux paramètres pour trouver le quadrant du résultat.

math.ceil

math.ceil( x )

Renvoie le plus petit entier supérieur ou égal à x.

math.cos

math.cos( x )

Renvoie le cosinus de x (exprimé en radians).

math.cosh

math.cosh( x )

Renvoie le cosinus hyperbolique de x.

math.deg

math.deg( x )

Renvoie l'angle x (donné en radians) en degrés.

math.exp

math.exp( x )

Renvoie la valeur $e^x$.

math.floor

math.floor( x )

Renvoie le plus grand entier inférieur ou égal à x.

math.fmod

math.fmod( x, y )

Renvoie le reste de la division de x par y avec arrondi du quotient vers zéro. Par exemple, math.fmod( 10, 3 ) donne 1.

math.frexp

math.frexp( x )

Renvoie deux valeurs m et e telles que :

• si x est fini et différent de zéro : $x=m\times 2^e$, e est un entier, et la valeur absolue de m est dans l'intervalle $[0.5,1)$ ;
• si x vaut zéro : m et e valent 0 ;
• si x vaut NaN ou l'infini : m est x et e n'est pas défini.

math.huge

La valeur qui représente l'infini positif, supérieure ou égale à n'importe quelle autre valeur numérique.

math.ldexp

math.ldexp( m, e )

Renvoie $m\times 2^e$ (e doit être un entier).

math.log

math.log( x )

Renvoie le logarithme naturel de x.

math.log10

math.log10( x )

Renvoie le logarithme en base 10 de x.

math.max

math.max( x, ... )

Renvoie la valeur la plus grande parmi les paramètres reçus.

Le comportement avec les NaN n'est pas spécifé. Dans l'implémentation actuelle, NaN sera renvoyé si x est NaN, mais les autres NaN seront ignorés.

math.min

math.min( x, ... )

Renvoie la valeur la plus petite parmi les paramètres reçus.

Le comportement avec les NaN n'est pas spécifé. Dans l'implémentation actuelle, NaN sera renvoyé si x est NaN, mais les autres NaN seront ignorés.

math.modf

math.modf( x )

Renvoie deux nombres, la partie entière de x et la partie fractionnaire de x. Par exemple math.modf( 1.25 ) renvoie 1, 0.25.

math.pi

La valeur de $\pi$.

math.pow

math.pow( x, y )

Renvoie $x^y$. (Vous pouvez aussi utiliser l'expression x^y pour calculer cette valeur.)

math.rad

math.rad( x )

Renvoie l'angle x (donné en degrés) en radians.

math.random

math.random( m, n )

Renvoie un nombre pseudo-aléatoire.

Les paramètres m et n peuvent être omis, mais si ils sont présents ils doivent être convertibles en entiers.

• Sans paramètre, renvoie un réel dans l'intervalle $[0,1)$
• Avec un paramètre, renvoie un entier dans l'intervalle $[1,m]$
• Avec deux paramètres, renvoie un entier dans l'intervalle $[m,n]$

Notez qu'une sortie incorrecte peut être produite si m ou n sont inférieurs à −2147483648 ou supérieurs à 2147483647, ou si n - m est supérieur à 2147483646.

math.randomseed

math.randomseed( x )

Initialiser x avec la « graine » du générateur de nombres pseudo-aléatoires.

Notez qu'avec une même graine math.random produit la même séquence de nombres.

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

math.sin

math.sin( x )

Renvoie le sinus de x (donné en radians).

math.sinh

math.sinh( x )

Renvoie le sinus hyperbolique de x.

math.sqrt

math.sqrt( x )

Renvoie la racine carrée de x (vous pouvez également utiliser x^0.5 pour calculer cette valeur).

math.tan

math.tan( x )

Renvoie la tangente de x (donné en radians).

math.tanh

math.tanh( x )

Renvoie la tangente hyperbolique de x.

Bibliothèque du système d'exploitation

os.clock

os.clock()

Renvoie une approximation du temps CPU consommé par le programme, en secondes.

os.date

os.date( format, time )

Utiliser la fonction formatDate de la bibliothèque Language pour une mise en forme plus claire des dates.

Renvoie une chaîne ou une table contenant la date et l'heure, formatées en accord avec format. Si le format est absent ou s'il vaut nil, "%c" est utilisé.

Si time est fourni, il est utilisé comme heure à formater (voir os.time()). Sinon c'est l'heure courante qui est utilisée.

Si format commence par '!', alors l'heure utilisée est l'heure UTC plutôt que l'heure locale sur les serveurs. Après ce caractère optionnel, si format est la chaine "*t", la date est retournée dans une table avec les champs suivants :

• year (année complète) ;
• month (1–12) ;
• day (1–31) ;
• hour (0–23) ;
• min (0–59) ;
• sec (0–60) (pour permettre la seconde intercalaire) ;
• wday (numéro du jour dans la semaine en commençant par 1 pour dimanche) ;
• yday (jour de l’année) ;
• isdst (booléen vrai en heure d’été ; peut être absent si l’information n’est pas disponible).

Si format n'est pas "*t", alors la date est retournée en tant que chaine, formatée en accord avec les règles de la fonction C strftime.

os.difftime

os.difftime( t2, t1 )

Renvoie le nombre de secondes séparant t1 de t2.

os.time

os.time( table )

Renvoie un nombre représentant l'heure courante.

Retourne l'heure courante si appelé sans paramètre. Si une table est fournie, l'heure indiquée dans cette table est utilisée. Cette table doit avoir les champs year, month, et day, et peut aussi inclure les champs hour (12 par défaut), min (0 par défaut), sec (0 par défaut), et "isdst".

Bibliothèque Package

require

require( modulename )

Charge le module indiqué.

Tout d’abord, il regarde dans package.loaded[modulename] pour voir si le module est déjà chargé. Si c’est le cas, il retourne 2 $.

Sinon, il appelle chaque chargeur de la séquence package.loaders pour tenter de trouver un chargeur pour le module. Si un chargeur est trouvé, ce dernier est appelé. La valeur renvoyée par le chargeur est stockée dans package.loaded[modulename] et est renvoyée.

Voir la documentation de package.loaders pour les chargeurs disponibles.

Par exemple, si vous avez un module « Module:Giving » contenant les éléments suivants :

local p = {}

p.someDataValue = p.someDataValue = 'Salut !'

return p

Vous pouvez charger ce module depuis un autre via le code suivant dans cet autre module :

local giving = require( "Module:Giving" )

local value = giving.someDataValue -- value contient maintenant "Salut !"

package.loaded

Cette table contient la liste des modules chargés. Les clés sont les noms des modules, et les valeurs sont les valeurs retournées quand les modules ont été chargés.

package.loaders

Cette table contient une suite de fonctions de recherche utilisées pour charger des modules. Chaque fonction est appelée avec un seul paramètre, le nom du module à charger. Si la fonction trouve le module à charger, elle doit retourner une fonction qui effectuera le chargement réel du module, et sa valeur de retour sera retournée par require. Sinon elle devrait retourner nil.

Scribunto fournit deux fonctions de recherche :

1. Cherchez dans package.preload[modulename] pour la fonction de chargement
2. Regardez dans les modules fournis avec Scribunto pour le nom du module, et si cela échoue, regardez dans l’espace de noms Module :. Le préfixe « Module : » doit être fourni.

Notez que les chargeurs standards de Lua ne sont pas présents.

package.preload

Cette table contient les fonctions de chargement, utilisées par la première fonction de recherche de Scribunto incluse dans package.loaders.

package.seeall

package.seeall( table )

Définit la $3 de __index pour table à _G.

Bibliothèque de manipulation de chaines

Dans toutes les fonctions sur les chaines, le premier caractère est à la position 1 et non 0 comme en C, PHP ou JavaScript. Les index peuvent être négatifs, et dans ce cas ils correspondent à une position à partir de la fin de la chaine : -1 est le dernier caractère, -2 l'avant-dernier…

Attention : La bibliothèque string suppose que les caractères sont encodés sur un octet. Elle ne gère pas correctement les caractères unicode. Pour manipuler des chaînes Unicode, utilisez les méthodes correspondantes de la bibliothèque Scribunto Ustring.

string.byte

string.byte( s, i, j )

Si la chaîne est considérée comme un tableau d’octets, renvoie les valeurs d’octets pour s[i], s[i+1], ···, s[j]. La valeur par défaut de i est 1; La valeur par défaut de j est i. Identique à mw.ustring.byte().

string.char

string.char( ... )

Reçoit zéro ou plus entiers. Retourne une chaine de même longueur que le nombre de ses paramètres, dans laquelle chaque caractère a le code numérique interne égal au paramètre correspondant.

local value = string.char( 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21 ) --value contient maintenant "Salut !"

Voir mw.ustring.char() pour une fonction similaire qui utilise les points de code Unicode plutôt que les valeurs en bits.

string.find

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

Recherche la première correspondance de pattern dans la chaîne s. S’il trouve une correspondance, alors find renvoie les décalages en s où cette occurrence commence et se termine ; Sinon, il renvoie nil. Si le motif a des captures, alors dans une correspondance réussie, les valeurs capturées sont également renvoyées après les deux indices.

Un troisième paramètre optionnel init spécifie l'indice où commence la recherche, sa valeur par défaut étant 1 et pouvant être négative. Une valeur true pour le quatrième (et optionnel) paramètre plain désactive la fonctionnalité de recherche de motif, et transforme la fonction en une opération de recherche littérale de sous-chaine, aucun des caractères de pattern n'étant alors considéré comme ayant de sens particulier.

Notez que si plain est fourni, alors init doit l'être aussi (la valeur peut être nil).

Voir init pour une fonction similaire qui utilise les motifs Ustring et où le décalage init est en caractères au lieu d'octets.

string.format

string.format( formatstring, ... )

Retourne une version formatée de ses paramètres qui peuvent être en nombre variable, en suivant la description donnée dans son premier paramètre (qui doit être une chaine).

La chaîne de format utilise un sous-ensemble limité des spécifieurs de format printf :

• les attributs reconnus sont '-', '+', ' ', '#', et '0' ;
• les largeurs minimales de champ sont supportées jusqu'à 99. '*' n'est pas supporté ;
• les précisions sont supportées jusqu'à 99. '*' n'est pas supporté ;
• les modificateurs de longueur ne sont pas supportés ;
• les indicateurs de conversion reconnus sont : 'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%', et le non standard 'q' ;
• les indicateurs de position (par exemple « %2$s ») ne sont pas supportés.

L'option de conversion q est similaire à s mais formate la chaine de façon à ce qu'elle soit utilisable par l'interpréteur Lua de façon correcte: la chaine est écrite entre guillemets doubles, et tous les guillemets doubles, retours à la ligne, codes zéro ("\0") et les barres obliques inversées ("\") présentes dans la chaîne sont correctement échappées.

Les conversions entre chaine et nombre sont réalisées comme indiqué dans Types et valeurs; Les autres types ne sont pas automatiquement convertis en chaines. Les chaines contenant des codes 0 ("\0") ne sont pas correctement gérées.

Identique à mw.ustring.format().

string.gmatch

string.gmatch( s, pattern )

Renvoie une fonction d'itération qui, chaque fois qu'elle est appelée, retourne les captures de la correspondance suivante de pattern dans la chaine s. Si pattern ne spécifie pas de capture, alors la correspondance complète est renvoyée.

Pour cette fonction le caractère ^ au début du motif n'a pas de sens spécial car cela bloquerait l'itération. Il est traité comme un caractère littéral.

Voir mw.ustring.gmatch() pour une fonction similaire pour laquelle le motif est étendu comme décrit dans les Motifs Ustring.

string.gsub

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

Renvoie une copie de s dans laquelle toutes les occurrences (ou les n premières, si ce paramètre est renseigné) de pattern ont été remplacées par la chaîne de remplacement précisée dans repl. Elle peut être une chaine, une table ou une fonction. gsub retourne également comme deuxième valeur le nombre total de correspondances trouvées.

Si repl est une chaine, alors sa valeur est utilisée pour le remplacement. Le caractère % fonctionne comme un caractère d'échappement : toute séquence dans repl de la forme %d, avec d un entier entre 1 et 9, signifie la valeur de la d-ième sous-chaine capturée (voir plus bas). La séquence %0 correspond à la correspondance complète. La séquence %% correspond à un simple %.

Si repl est une table, alors cette table est utilisée pour chaque correspondance, en utilisant la première capture comme clé : si le motif ne spécifie pas de capture, alors la correspondance complète est utilisée comme clé.

Si repl est une fonction, alors cette fonction est appelée à chaque fois qu'une correspondance est trouvée, avec toutes les sous-chaines capturées en paramètres, dans l'ordre. Si le motif ne spécifie pas de capture, alors la correspondance complète est passée comme seul paramètre.

Si la valeur retournée par l'accès à la table ou par la fonction est une chaine ou un nombre, alors il est utilisé comme chaine de remplacement. Par contre, si la valeur retournée est nil ou false, alors aucun remplacement n'a lieu (ce qui signifie que la correspondance est conservée dans la chaine).

Voir mw.ustring.gsub() pour une fonction similaire pour laquelle les motifs sont décrits dans Motifs Ustring.

string.len

string.len( s )

Reçoit une chaîne de caractères et renvoie sa longueur en octets. Les caractères ASCII NUL ne sont pas ignorés. Ainsi "a\000bc\000" a une longueur de 5. Équivalent à #s.

Voir mw.ustring.len() pour une fonction similaire utilisant les points de code Unicode plutôt que les octets.

string.lower

string.lower( s )

Reçoit une chaîne de caractères et retourne une copie de cette chaîne avec tous les caractères ASCII en majuscule changés en minuscules. Tous les autres caractères sont laissés tels quels (notamment les lettres accentuées comme É sont inchangées).

Voir mw.ustring.lower() pour une fonction similaire pour laquelle tous les caractères concernés par la casse en Unicode sont convertis.

string.match

string.match( s, pattern, init )

Cherche la première correspondance de pattern dans la chaîne. Si une correspondance est trouvée, match retourne les captures correspondantes au motif, sinon il retourne nil. Si pattern ne précise pas de capture, alors la correspondance complète est renvoyée.

Un troisième paramètre optionnel init permet de spécifier la position de départ dans la chaine où commencer la recherche. Sa valeur par défaut est 1. Il peut être négatif.

Voir mw.ustring.match() pour une fonction similaire pour laquelle les motifs sont décrits dans Motifs ustring et le décalage init est en caractères plutôt qu'en octets.

string.rep

string.rep( s, n )

Renvoie une chaîne qui est la concaténation de n copies de la chaîne s. Identique à mw.ustring.rep().

string.reverse

string.reverse( s )

Renvoie une chaine qui est la chaîne s retournée (début ↔ fin, octet par octet).

string.sub

string.sub( s, i, j )

Retourne une sous-chaine de s qui débute à la position i et continue jusqu'à la position j, i et j pouvant être négatifs. Si j vaut `nil` ou est omis, cela continuera jusqu’à la fin de la chaine.

En particulier >string.sub( s, 1, j ) retourne un préfixe de s de longueur j, et string.sub( s, -i ) retourne un suffixe de longueur i de s.

Voir mw.ustring.sub() pour une fonction similaire pour laquelle i et j sont exprimés en caractères et non en octets.

string.ulower

string.ulower( s )

Alias de mw.ustring.lower().

string.upper

string.upper( s )

Reçoit une chaine et retourne une copie de cette chaine avec tous les caractères ASCII minuscule changés en majuscule. Tous les autres caractères sont laissés tels quels.

Voir mw.ustring.upper() pour une fonction similaire pour laquelle les caractères concernés par la casse en Unicode seront convertis.

string.uupper

string.uupper( s )

Alias pour mw.ustring.upper().

Motifs (pattern)

En Lua, les motifs sont similaires aux expressions régulières sans pour autant être identiques. Voici quelques différences avec les expressions régulières et les PCRE :

• le caractère d’échappement est le symbole du pour cent %, non l’antislash \ ;
• le point . remplace tout caractère, y compris le retour charriot ;
• il n’y a pas d'option pour être insensible à la casse ;
• l’alternative | n'est pas définie ;
• les quantificateurs (*, +, ?, et -) ne peuvent s’appliquer qu’à un caractère ou une classe de caractère, pas à un groupe de capture ;
• le seul quantificateur non possessif est -, qui est équivalent au quantificateur *? de PCRE ;
• il n’est pas possible de quantifier de manière précise (comme le ferait {n,m} avec PCRE) ;
• Les seules assertions de largeur nulle sont ^, $ et le modèle %f[set] « frontier » ; les assertions telles que \b ou (?=···) de PCRE ne sont pas présentes.
• les motifs eux-mêmes ne reconnaissent pas les caractères d’échappement tels que \ddd (cependant, puisque les motifs sont des chaines, ces types d’échappement peuvent être utilisés dans la chaine utilisée pour créer le motif).

Notez aussi qu’un motif ne peut contenir aucun octet nul (caractère ASCII « NULL », "\0"). Utilisez %z à la place.

Voir aussi Motifs ustring pour des motifs similaires utilisant cette fois les caractères Unicode (Sur MediaWiki, tous les caractères non ASCII sont codés sur plusieurs octets en UTF-8).

Classes de caractères

Une classe de caractères est utilisée pour représenter un ensemble de caractères (un caractère - géré par la bibliothèque string standard de Lua avec Scribunto sur MediaWiki - est seulement un octet : les caractères de l’intervalle \000 à \127 sont considérés comme codés en ASCII).

Les combinaisons suivantes sont autorisées pour représenter une classe de caractères :

x	(où x n’est aucun des caractères magiques ^$()%.[]*+-?) représente le caractère x lui-même.
.	(le point de ponctuation) représente tous les personnages.
%a	Représente toutes les lettres ASCII.
%c	Représente tous les caractères de contrôle ASCII.
%d	Représente les chiffres latins.
%l	Représente les lettres ASCII minuscules.
%p	Représente les signes de ponctuation et les symboles du jeu de caractères ASCII.
%s	Représente les caractères d’espacement ASCII (l’espace et les contrôles de tabulation ou de saut de ligne).
%u	Représente les lettres ASCII majuscules.
%w	Représente les caractères alphanumériques ASCII (0-9a-zA-Z).
%x	Représente les chiffres hexadécimaux (0-9A-Fa-f).
%z	Représente le caractère NULL \000 (le caractère de contrôle dont la valeur numérique est nulle).
%A	Tous les caractères (octets) qui ne sont pas dans %a.
%C	Tous les caractères (octets) qui ne sont pas dans %c.
%D	Tous les caractères (octets) qui ne sont pas dans %d.
%L	Tous les caractères (octets) qui ne sont pas dans %l.
%P	Tous les caractères (octets) qui ne sont pas dans %p.
%S	Tous les caractères (octets) qui ne sont pas dans %s.
%U	Tous les caractères (octets) qui ne sont pas dans %u.
%W	Tous les caractères (octets) qui ne sont pas dans %w.
%X	Tous les caractères (octets) qui ne sont pas dans %x.
%Z	Tous les caractères (octets) qui ne sont pas dans %z.
%y	(où y est un caractère non alphanumérique) représente le caractère y. C’est la façon habituelle d’utiliser explicitement un caractère « magique » (ayant un sens de contrôle des motifs). N’importe quel caractère de ponctuation (même non magique) peut être précédé d’un '%' lorsqu’il est utilisé pour se représenter dans un motif.
[set]	Représente la classe qui est l’union de tous les caractères de set. Une plage de caractères peut être spécifiée en séparant les caractères de fin de la plage par un '-'. Toutes les classes %y décrites ci-dessus peuvent également être utilisées comme composants dans set. Tous les autres personnages de set se représentent eux-mêmes. Par exemple, [%w_] (ou [_%w]) représente tous les caractères alphanumériques plus le trait de soulignement, et [0-7] représente les chiffres du système octals. Pour inclure des '-' littéraux dans l’ensemble, utilisez '%-', donc [0-7%l%-] représente les chiffres du système octal plus les lettres minuscules plus le caractère '-'. L’interaction entre les intervalles et les classes n’est pas définie. Ainsi, les motifs tels que [%a-z] ou [a-%%] n’ont aucune signification.
[^set]	Représente le complément de set, où set est interprété suivant la définition ci-dessus.

Élément de motif (pattern item)

Un élément de motif peut être :

• un singleton d'une classe de caractère, qui correspond à un caractère unique dans la classe ;
• un singleton d'une classe de caractère suivi d'un '*', qui correspond à 0 ou plus répétition(s) de tout caractère de la classe. Cette répétition correspond toujours à la plus longue répétition possible ;
• un singleton d'une classe de caractère suivi d'un '+', qui correspond à 1 ou plus répétition(s) de tout caractère de la classe. Cette répétition correspond toujours à la plus longue répétition possible ;
• un singleton d'une classe de caractère suivi d'un '-', qui correspond également à 0 ou plus répétition(s) de tout caractère de la classe. Contrairement à '*' cette répétition correspond toujours à la plus petite répétition possible ;
• un singleton d'une classe de caractères suivi d'un '?', qui correspond à 0 ou 1 occurrence d'un caractère de la classe ;
• %n, pour n compris entre 1 et 9. Cet élément correspond à une sous-chaine valant la n-ième chaine capturée (voir plus bas) ;
• %bxy, ou x et y sont deux caractères distincts. Cet élément correspond à la chaine qui commence par x, se termine par y, et où x et y sont équilibrés (balanced). Cela signifie, en lisant la chaine de gauche à droite, compter +1 pour chaque x et -1 pour chaque y, le y terminal est le premier y pour lequel le compte atteint 0. Par exemple, l'élément %b() correspond à une expression avec des parenthèses équilibrées.
• %f[set], un motif de frontière ; correspond à une chaine vide dont la position est telle que le caractère suivant appartient à la classe de caractères set et le précédent n’y appartient pas. L’ensemble set est interprété comme défini précédemment. Le début et la fin du sujet sont traités comme s’il s’agissait du caractère nul '\0'.
  Notez que les motifs de frontière était présents mais non documentés dans Lua 5.1, puis ont été ajoutés officiellement dans la version 5.2. L’implémentation dans Lua 5.2.1 est identique à celle dans la version 5.1.0.

Motif (pattern)

Un motif est une séquence d'éléments de motif.

Un ^ au début d’un motif ancre la correspondance au début de la chaîne d’objet. Un $ à la fin d'un motif ancre la correspondance à la fin de la chaîne sujet. Dans d'autres positions, ^ et $ n'ont pas de signification particulière et se représentent eux-mêmes.

Captures

Un motif peut contenir des sous-motifs entre parenthèses ; ils décrivent des captures. Lorsqu'une correspondance réussit, les sous-chaînes de la chaîne d'objet qui correspondent aux captures sont stockées ("capturées") pour une utilisation future. Les captures sont numérotées selon leurs parenthèses gauches. Par exemple, dans le modèle (a*(.)%w(%s*)), la partie de la chaîne correspondant à a*(.)%w(%s*) est stocké en tant que première capture (et porte donc le numéro 1) ; le caractère correspondant à . est capturé avec le numéro 2, et la partie correspondant à %s* a le numéro 3.

Les captures peuvent apparaitre dans la chaine de motif elle-même, et faire référence à une capture faite plus tôt dans le motif. Par exemple, ([a-z])%1 va correspondre à n'importe quelle paire de lettres en minuscule identiques, tandis que ([a-z])([a-z])([a-z])[a-z]%3%2%1 correspond à tout palindrome de 7 lettres.

La capture vide () est spéciale et capture la position courante dans la chaine (un nombre). Par exemple si on applique le motif "()aa()" sur la chaine "flaaap", il y aura deux captures : 3 et 5.

Limitations connues : à la différence des motifs de la bibliothèque Ustring, les motifs de la bibliothèque String ne peuvent pas contenir plus de 32 captures. Si le motif en a plus, alors la fonction String génèrera une erreur. Parce que la bibliothèque Ustring possède sont propre maximum de 10 000 octets pour les motifs (à la différence de la bibliothèque String), il n'est par conséquent pas possible d'utiliser un motif qui dépasserait ces deux limites, car il ne sera pas compatible avec les deux bibliothèques.

Bibliothèque table

La plupart des fonctions de la bibliothèque table supposent que la table soit une séquence.

Les fonctions table.foreach(), table.foreachi(), et table.getn() sont encore disponibles mais sont obsolètes; utilisez une boucle for avec table.setn(), une boucle for avec ipairs(), et l'opérateur de longueur à la place. La fonction table.setn() est complètement obsolète, et génèrera une erreur si elle est utilisée.

table.concat

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

Étant donné un tableau où tous les éléments sont des nombres ou des chaines, on retourne table[i] .. sep .. table[i+1] ··· sep .. table[j].

La valeur par défaut de sep est une chaine vide, la valeur par défaut de i est 1, et la valeur par défaut de j est la longueur de la table. Si i est plus grand que j, la fonction retourne une chaine vide.

table.insert

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

Insère l'élément valeur à la position pos dans table, décalant si nécessaire vers la fin les éléments pour faire la place nécessaire. La valeur par défaut de pos est la longueur de la table plus 1, ainsi table.insert( t, x ) ajoute x à la fin de la table t.

Les éléments jusqu'à #table sont décalés. Voir Opérateur de longueur pour le comportement si la table n'est pas une séquence.

Note: lors de l'utilisation du paramètre pos, value ne devrait pas être nil. Tenter d’insérer une valeur nil explicite au milieu d'une table donnera un comportement indéfini, qui peut supprimer des éléments dans la table de manière imprévisible.

table.maxn

table.maxn( table )

Retourne le plus grand index positif de la table, ou zéro si la table ne possède pas d'index numérique positif.

Pour ce faire, cette fonction itère sur l'ensemble de la table et pourrait être écrite comme suit :

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 )

Enlève de table l'élément se trouvant à la position pos, en décalant si nécessaire « vers le bas » les éléments « au dessus » pour combler l'espace libre créé. Retourne la valeur de l'élément supprimé. La valeur par défaut de pos est la longueur de la table, donc le code table.remove( t ) supprime le dernier élément de la table t.

Les éléments jusqu'à #table sont décalés. Voir l'opérateur de longueur pour le comportement si la table n'est pas une séquence.

table.sort

table.sort( table, comp )

Trie les éléments du tableau dans l'ordre indiqué, sur place, de table[1] à table[#table]. Si comp est fourni, alors ce doit être une fonction qui reçoit deux éléments de type tableau, et renvoie true lorsque le premier est inférieur au second (de sorte que not comp(a[i+1],a[i]) vaudra true après le tri). Si comp n'est pas fourni, alors l'opérateur standard Lua < est utilisé à la place. L'algorithme de tri n'est pas stable. Cela signifie que des éléments considérés comme égaux peuvent voir leur position modifiée lors du tri.

Bibliothèques Scribunto

Toutes les bibliothèques Scribunto se trouvent dans la table mw.

Fonctions de base

mw.addWarning

mw.addWarning( text )

ajoute une alerte qui est affichée en en-tête lors de la prévisualisation. text est traité en tant que wikitexte.

mw.allToString

mw.allToString( ... )

Appelle tostring() sur tous ses paramètres, puis concatène les résultats avec une tabulation comme séparateur.

mw.clone

mw.clone( value )

Crée une copie de la valeur. Toutes les tables (et leurs méta-tables) sont reconstruites de zéro. Les fonctions restent partagées quoi qu'il en soit.

mw.getCurrentFrame

mw.getCurrentFrame()

Retourne l'objet frame courant, généralement l'objet frame du dernier appel à #invoke.

mw.incrementExpensiveFunctionCount

mw.incrementExpensiveFunctionCount()

Ajoute un au compteur des « fonctions d’analyse coûteuses », et génère une procédure en exception si ce compteur dépasse la limite (voir $wgExpensiveParserFunctionLimit ).

mw.isSubsting

mw.isSubsting()

Renvoie true si le #invoke courant est en train d'être « substé », false dans le cas contraire. Voir Retourner du texte plus haut pour connaitre la différence entre un #invoke substé ou non.

mw.loadData

mw.loadData( module )

Parfois un module a besoin de grandes tables de données. Par exemple, un module générique de conversion d'unités devrait avoir une grande table contenant toutes les unités connues et leurs facteurs de conversion. Et parfois ces modules vont être utilisés de nombreuses fois dans une même page. Interpréter de grandes tables de données pour chaque {{#invoke:}} peut prendre un temps non négligeable. Pour éviter ce problème, la fonction mw.loadData() existe.

mw.loadData fonctionne comme require() avec les différences suivantes :

• le module n'est évalué qu'une fois par page, plutôt qu'une fois par appel à {{#invoke:}} ;

• le module chargé n'est pas enregistré dans package.loaded ;
• la valeur renvoyée par le module chargé doit être une table, les autres types ne sont pas gérés ;
• la table retournée (et ses sous-tables) ne peut contenir que des booléens, des nombres, des chaines et d'autres tables. Les autres types, en particulier les fonctions, ne sont pas autorisés ;
• la table renvoyée (et toutes ses sous-tables) ne doivent pas avoir de méta-tables ;
• toutes les clés de la table doivent être des booléens, des nombres ou des chaînes ;

• la table réellement retournée par mw.loadData() a des méta-méthodes qui fournissent un accès en lecture seule à cette table. Dans la mesure où elle ne contient pas directement les données, pairs() et ipairs() fonctionnent mais les autres méthodes, y compris #value, next(), et les fonctions de la bibliothèque Table, ne fonctionneront pas correctement.

Dans l'hypothétique module évoqué plus haut, le module pourrait être « Module:Convert » et les données pourraient être stockées dans « Module:Convert/data ». Le module utiliserait local data = mw.loadData( 'Module:Convert/data' ) pour charger efficacement les données.

mw.loadJsonData

mw.loadJsonData( page )

C'est la même chose que mw.loadData() ci-dessus, sauf qu'elle charge les données de pages JSON plutôt que de tables Lua. Le contenu JSON doit être un tableau ou un objet. Voir aussi mw.text.jsonDecode().

mw.dumpObject

mw.dumpObject( object )

Renvoie une représentation lisible par un humain de objet, sous forme de chaine.

mw.log

mw.log( ... )

Envoie ses paramètres à mw.allToString() puis ajoute le résultat au tampon des enregistrements (log).

Dans la console de debug, la fonction print() est un alias de cette fonction.

mw.logObject

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

Appelle mw.dumpObject() et ajoute la chaine résultante au tampon de journalisation (ce tampon est affiché dans la console de modification des modules MediaWiki, et en commentaire à la fin du contenu dans le code HTML de la page). Si le paramètre prefix est renseigné, sa valeur textuelle sera ajoutée au tampon, suivie d'un signe égal, avant que la chaine produite y soit ajoutée (le texte journalisé sera donc « prefix = chaine-objet »).

L'objet Frame

L'objet frame est l'interface des paramètres passés à {{#invoke:}}, et au parseur.

Notez qu’il n’existe pas de bibliothèque pour les frame, et il n’existe pas de variable globale nommée frame. Un objet frame est habituellement obtenu en étant passé comme paramètre à la fonction appelée par {{#invoke:}} et peut aussi être obtenue depuis mw.getCurrentFrame().

frame.args

Une table pour accéder aux paramètres passés à l'objet frame. Par exemple si un module est appelé avec le wikitexte suivant :

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

alors frame.args[1] renverra "arg1", frame.args[2] renverra "arg2", et frame.args['name'] (ou frame.args.name) renverra "arg3". Il est également possible d'itérer sur les paramètres en utilisant pairs( frame.args ) ou ipairs( frame.args ). Néanmoins, la manière dont sont implémentés les itérateurs de table en Lua fait que l'itération sur les arguments les retourne dans un ordre indéfini, et il n'existe aucun moyen de savoir dans quel ordre les paramètres ont été fournis dans le wikicode.

Notez que les valeurs de cette table sont toujours des chaines. tonumber() peut être utilisé pour les convertir en nombres si besoin. Les clés, toutefois, sont des nombres même si elles sont fournies explicitement comme paramètres nommés lors de l'appel : {{#invoke:module|function|1|2=2}} donne les chaines "1" et "2" indicées par les clés numériques 1 et 2.

Comme dans l'appel à des modèles dans MediaWiki, les paramètres nommés sont nettoyés (les espaces en début et fin de paramètre sont supprimés), alors que les paramètres non nommés sont passés tels quels (avec leurs espaces éventuels en début et fin).

Pour des raisons de performance, frame.args utilise une méta-table au lieu de contenir directement les paramètres. Les valeurs des paramètres sont demandés à MediaWiki lors d'une tentative d'accès à leur valeur. Cela signifie que la plupart des méthodes sur les tables ne fonctionnent pas correctement sur la table des paramètres, incluant #frame.args, next( frame.args ), et les fonctions de la bibliothèque table.

Si la syntaxe du préprocesseur (comme l'appel de modèles, ou des arguments avec des accolades triples) est utilisée dans un argument de #invoke, celui-ci ne sera pas évalué, après être passé à Lua, sauf si Lua a besoin d’utiliser sa valeur. Si certaines balises spéciales écrites en notation XML (par exemple ‎<pre>, ‎<nowiki>, ‎<gallery> et ‎<ref>) sont utilisées comme argument de #invoke, elles sont converties en « marqueurs de bande » — des chaînes spéciales commençant par le caractère DELETE (ASCII 127) et qui sont remplacées par du code HTML au retour de #invoke.

frame:callParserFunction

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

Notez l'utilisation de paramètres nommés.

Appelle une parser-function et retourne le résultat correspondant. C'est préférable à frame: preprocess, mais quand c'est possible, les fonctions natives Lua ou Scribunto doivent être préférées à l'utilisation de cette interface.

Les appels suivants sont à peu près équivalents au wikitexte indiqué :

-- {{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'
} )

Notez que − comme avec frame:expandTemplate() − le nom de la fonction et les paramètres ne sont pas pré-processés avant d'être passés au parser-function.

frame:expandTemplate

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

Notez l'utilisation de paramètres nommés.

Ceci équivaut à appeler frame:callParserFunction() avec 'msg' comme nom de fonction (voir les mots magiques modificateurs de transclusion) et avec args commençant par title.

Applique une transclusion. L'appel :

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

fait à peu près la même chose en Lua que {{template|arg1|arg2|name=arg3}} en wikicode. Comme pour la transclusion, si le titre qui est passé ne contient pas de préfixe d'espace de noms, il sera supposé appartenir à l'espace de noms Template: des modèles.

Notez que le titre et les paramètres ne sont pas pré-processés avant d'être passés au modèle :

-- Ceci est à peu près équivalent au wikicode {{template|{{!}}}}
frame:expandTemplate{ title = 'template', args = { '|' } }
frame:callParserFunction{ 'msg', { 'template', '|' } }

-- Ceci est à peu près équivalent au wikicode {{template|{{((}}!{{))}}}}
frame:expandTemplate{ title = 'template', args = { '{{!}}' } }
frame:callParserFunction{ 'msg', { 'template', '{{!}}' } }

frame:extensionTag

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

Ceci équivaut à appeler frame:callParserFunction() avec pour nom de fonction '#tag' (voir les mots magiques) et avec name et content placés avant args.

-- Ces expressions sont équivalentes
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'
} )

-- Ces expressions sont équivalentes
frame:extensionTag{ name = 'ref', content = 'some text', args = { 'some other text' } }
frame:callParserFunction( '#tag', { 'ref',
    'some text', 'some other text'
} )

frame:getParent

frame:getParent()

Appelé sur l'objet frame créé par un {{#invoke:}}, renvoie l'objet frame de la page qui a appelé le {{#invoke:}}. Appelé sur cet objet frame renvoie nil.

Par exemple, si le modèle {{Example}} contient le code {{#invoke:ModuleName|FunctionName|A|B}}, et qu'une page transclut ce modèle avec le code {{Example|C|D}}, alors dans Module:ModuleName, l'appel de frame.args[1] et frame.args[2] renvoient "A" et "B", et l'appel de frame:getParent().args[1] et frame:getParent().args[2] renvoient "C" et "D" avec frame qui est le premier argument de l'appel de fonction.

frame:getTitle

frame:getTitle()

Renvoie le titre associé à l'objet frame sous forme de chaine. Pour l'objet frame créé par {{#invoke:}}, c'est le titre du module invoqué.

frame:newChild

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

Notez l'utilisation de paramètres nommés.

Crée un nouvel objet frame qui est un enfant de l'objet frame courant, avec optionnellement le titre et les paramètres indiqués.

Ceci sert principalement pour la console de debogage afin de tester les fonctions qui sont normalement appelées par {{#invoke:}}. Le nombre de frames créées à un instant donné est limité.

frame:preprocess

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

Cela développe le wikicode dans le contexte du cadre (objet frame), c’est-à-dire que les modèles, les fonctions d’analyse syntaxique et les paramètres tels que $param 1 sont développés, et renvoie le texte développé. Certaines balises spéciales écrites en notation de style XML, telles que ‎<pre>, ‎<nowiki>, ‎<gallery> et ‎<ref>, seront remplacées par des « marqueurs de bande » — des chaînes spéciales qui commencent par un caractère de suppression (ASCII 127), à remplacer par HTML après avoir été renvoyées par #invoke.

Si vous développez un seul modèle, utilisez frame:expandTemplate au lieu d'essayer de construire une chaîne wikicode à passer à cette méthode. C'est plus rapide et moins sujet aux erreurs si les arguments contiennent des caractères pipe '|' ou autre balisage wiki.

Si vous souhaitez développer une seule fonction d’analyse, utilisez frame:callParserFunction pour les mêmes raisons.

frame:getArgument

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

Retourne un objet pour le paramètre indiqué, ou nil si ce paramètre n'est pas présent.

L'objet retourné a une méthode object:expand(), qui retourne le wikitexte traité de ce paramètre.

frame:newParserValue

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

Retourne un objet avec une méthode object:expand(), qui retourne le résultat de frame:preprocess( chaine ).

frame:newTemplateParserValue

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

Notez l'utilisation de paramètres nommés.

Retourne un objet avec une méthode object:expand(), qui retourne le résultat de frame:expandTemplate appelé avec les paramètres indiqués.

frame:argumentPairs

frame:argumentPairs()

Identique à pairs( frame.args ). Inclus pour compatibilité arrière.

Bibliothèque de hachage

mw.hash.hashValue

mw.hash.hashValue( algo, chaine )

Renvois la somme de contrôle de chaine suivant l'algorithme spécifié. Les algorithmes valides peuvent être obtenus par mw.hash.listAlgorithms().

mw.hash.listAlgorithms

mw.hash.listAlgorithms()

Retourne la liste des noms des algorithmes de hachage supportées par mw.hash.hashValue().

Bibliothèque html

mw.html est une interface fluide pour construire du code HTML complexe pour Lua. Le code est ainsi à la fois plus concis et plus clair. Un objet mw.html peut être créé en utilisant mw.html.

Les fonctions documentées sous la forme mw.html.name sont disponibles dans la table globale mw.html ; Les fonctions documentées comme mw.html :name et html :name sont des méthodes d’un objet mw.html (voir mw.html.name).

Un exemple de base pourrait ressembler à ceci :

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 )

Crée un nouvel objet mw.html contenant un élément html balise. Vous pouvez également passer une chaine vide au paramètre balise afin de créer un objet mw.html vide.

args peut être une table avec les clés suivantes :

• args.selfClosing : force la balise courante à se fermer, même si mw.html ne la reconnait pas comme auto-fermante
• args.parent : parent de l'instance de mw.html actuel (destiné à un usage interne)

mw.html:node

html:node( builder )

Ajoute un nœud enfant (html) à l'objet mw.html actuel. Si html est nil, l'objet n'est pas modifié. html peut être une objet mw.html ou une chaine représentant le code HTML d'un élément.

mw.html:wikitext

html:wikitext( ... )

Ajoute un nombre indéterminé de wikitexte à l'objet mw.html.

Notez que cette opération s'arrête au premier élément nil rencontré.

Le texte wiki de base sera analysé, comme l'HTML, les liens, le texte en gras, les listes ou les tables. Cependant, les modèles et les fonctions de partage ne seront pas évalués s'ils sont transmis directement à cette fonction, à moins qu'ils ne proviennent des paramètres du modèle. Ces textes seront rendus en texte clair à la place. Pour les évaluer, ils devront être passés dans frame:preprocess.

mw.html:newline

html:newline()

Ajoute une nouvelle ligne à l'objet mw.html. Utile quand utilisé avant et après mw.html:wikitext(), lorsque le wiki-texte contient des listes ou des tables dont la syntaxe n'a une signification particulière que lorsqu'elle est présente au début d'une ligne.

mw.html:tag

html:tag( tagName, args )

Ajoute un nouveau nœud enfant avec le tagName donné au générateur, et renvoie une instance de mw.html représentant ce nouveau nœud. Le paramètre args est identique à celui de mw.html.create.

Noter que contrairement à d'autres méthodes telles que html:node(), cette méthode ne renvoie pas l'instance mw.html actuelle, mais l'instance mw.html de la balise nouvellement insérée. Assurez-vous d'utiliser html:done() pour remonter à l'instance parent mw.html, ou html:allDone() si vous avez des balises imbriquées à plusieurs niveaux.

mw.html:attr

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

Définit un attribut HTML avec le name et value donnés sur le nœud. Alternativement, une table contenant les couples d’attributs nom = valeur peut être passée. Avec la première forme, une valeur nulle désactive l’attribut name si cet attribut avait une valeur définie.

mw.html:getAttr

html:getAttr( name )

Obtiens la valeur de l'attribut HTML nom précédemment définie en utilisant html:attr().

mw.html:addClass

html:addClass( class )

Ajoute un nom de classe à l'attribut de classe du nœud. Si classe est nil, aucune modification n'est effectuée.

mw.html:css

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

Définit une propriété CSS name avec comme valeur value sur le nœud. Alternativement, une table contenant des couples de propriétés nom = valeur peut être passée. Avec la première forme, une valeur nulle désactive la propriété donnée si celle-ci avait une valeur définie précédemment.

mw.html:cssText

html:cssText( css )

Ajoute du code CSS brut à l'attribut du nœud courant. Si css est nil, aucune modification n'est effectuée.

mw.html:done

html:done()

Renvoie le nœud parent dans lequel le nœud courant a été créé. Comme jQuery.end, il s'agit d'une fonction pratique pour permettre la construction de plusieurs nœuds enfants pour être chainés en une seule déclaration.

mw.html:allDone

html:allDone()

Comme html:done(), mais traverse tout le chemin vers le nœud racine de l'arbre et le retourne.

Bibliothèque language

Les codes des langues sont décrits dans Language code. Bon nombre des codes de langue de MediaWiki sont similaires aux codes de langue IETF, mais tous les codes de langue de MediaWiki ne sont pas des codes langue IETF valides ou vice-versa.

Les fonctions documentées sous la forme mw.language.nom sont disponibles dans la table globale mw.language. Les fonctions documentées sous la forme mw.language:nom et lang:nom sont des méthodes d'un objet Language (voir mw.language.new).

mw.language.fetchLanguageName

mw.language.fetchLanguageName( code, inLanguage )

Le nom complet de la langue correspondant au code indiqué : par défaut dans cette langue (autonyme), ou traduit dans la langue indiquée dans inLanguage.

mw.language.fetchLanguageNames

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

Cherche la liste des langues reconnues par MediaWiki, et retourne une table de correspondance nom de langue ⇔ code de langue.

Par défaut, le nom de langue retourné est celui dans la langue en question ; renseigner un code de langue pour enLangue permet de renvoyer tous les noms dans cette langue.

Par défaut, seules les noms de langue connus par MediaWiki sont renvoyés ; renseigner 'all' pour include permet le renvoi de toutes les langues disponibles (e.g. depuis Extension:CLDR/fr ), tandis que renseigner 'mwfile' permet de renvoyer seulement les langues qui ont des traductions incluses dans le cœur de MediaWiki ou dans des extensions activées. Pour sélectionner explicitement le défaut, il faut renseigner 'mw'.

mw.language.getContentLanguage

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

Retourne un nouvel objet Language correspondant à la langue du wiki sur lequel on se trouve.

mw.language.getFallbacksFor

Chaînes de repli

mw.language.getFallbacksFor( code )

Renvoie une liste des codes de langue de MediaWiki pour le code spécifié.

mw.language.isKnownLanguageTag

mw.language.isKnownLanguageTag( code )

Retourne true si le code indiqué est un code reconnu par MediaWiki.

Un code de langue est « connu » si c'est un « valid built-in code » (c'est à dire qui renvoie true via mw.language.isValidBuiltInCode) et renvoie une chaine non vide via mw.language.fetchLanguageName.

mw.language.isSupportedLanguage

mw.language.isSupportedLanguage( code )

Vérifie si la localisation est disponible dans MediaWiki pour le code de langue indiqué.

Un code de langue est « supporté » si c'est un code « valide » (qui renvoie true via mw.language.isValidCode), ne contient pas de lettres en majuscule, et a un fichier dans la version courante de MediaWiki.

Il est possible pour un code de langue d'être « supporté » mais pas encore « connu » (c'est à dire renvoyant true via mw.language.isKnownLanguageTag).

Veuillez noter aussi que certains codes sont « supportés » bien que mw.language.isValidBuiltInCode renvoie false (ces codes sont d'anciens codes « connus » encore utilisés dans les éditions linguistiques de Wikipédia et d'autres projets Wikimedia, mais ne sont pas compatibles avec les normes internationales ou ne sont pas enregistrés dans le registre IANA des identifiants linguistiques pour BCP 47 ; par exemple tokipona). Certains de ces wikis (et les données traduites nécessaires) ont été migrés pour utiliser les codes recommandés (mais pas encore tous). D'autres projets wikis hors de Wikimedia utilisent aussi encore certains de ces codes, ou bien peuvent déjà supporter les codes standards dans leurs fichiers de configuration, ce qui rend obsolète ces anciens codes non standards qui peuvent cependant être encore reconnus comme synonymes afin de faciliter les migrations de données.

mw.language.isValidBuiltInCode

mw.language.isValidBuiltInCode( code )

Retourne vrai si le code de langue est ou pourrait être disponible dans MediaWiki.

Le code peut en effet ne correspondre à aucun langage connu.

Un code de langue est un « valid built-in code » si c'est un code « valide » (càd qu'on obtient true via mw.language.isValidCode) ; il est constitué dans ce cas-là seulement de caractères du jeu de codage ASCII (lettres latines de base, chiffres arabes européens, ou traits d'union), et devrait respecter une syntaxe conforme : il devrait comporter au moins deux caractères, commencer par une lettre, ne pas finir par un trait d'union, ne contenir aucune paire de traits d'union consécutifs, ni aucune séquence de lettres ou chiffres (séparées par des traits-d'union) de plus de 8 caractères.

Notez que certains codes sont « supportés » (c'est à dire qu'on obtient true via mw.language.isSupportedLanguage) même si la présente fonction renvoie false.

mw.language.isValidCode

mw.language.isValidCode( code )

Retourne true si une chaine de code langue est d'une forme valide, qu'il existe ou pas. Ceci inclut les codes qui sont utilisés pour la personnalisation par les espaces de noms MediaWiki.

Le code peut ne correspondre à aucune langue connue.

Un code de langue est valide s'il ne contient que des caractères autorisés dans un texte HTML, aucun caractère de contrôle ASCII (tabulation, saut de ligne, retour chariot), ne contient pas certains autres caractères (deux-points, apostrophe simple ou double, barre oblique renversée ou non, crochets, accolades, esperluette, symbole dièse) et est dans ce cas-là autorisé dans un titre de page.

mw.language.new

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

Crée un nouvel objet Language. Les objets Language n'ont aucune propriété accessible, mais possèdent de nombreuses méthodes qui sont documentées ci-dessous.

Il y a une limite au nombre de code de langue distinct qui peuvent-être utilisés sur une page. Dépasser cette limite génère une erreur.

mw.language:getCode

lang:getCode()

Retourne le code de langue correspondant à cet objet.

mw.language:toBcp47Code

lang:toBcp47Code()

Retourne le code de langue de la norme BCP-47 pour cet objet Language. Il s’agit du code de langue approprié en HTML, par exemple comme valeur de l’attribut lang.

mw.language:getFallbackLanguages

lang:getFallbackLanguages()

Renvoie une liste de codes de langue de replis de MediaWiki pour cet objet langue. Équivalent à mw.language.getFallbacksFor( lang:getCode() ).

mw.language:isRTL

lang:isRTL()

Retourne true si la langue est écrite de droite à gauche, false si elle est écrite de gauche à droite.

mw.language:lc

lang:lc( s )

Convertit chaine en minuscules, en respectant les règles particulières de la langue correspondante.

Quand la bibliothèque ustring est chargée, la fonction mw.ustring.lower() est codée en appelant mw.language.getContentLanguage():lc( s ).

mw.language:lcfirst

lang:lcfirst( s )

Convertit le premier caractère de la chaine en minuscule, comme le fait lang:lc().

mw.language:uc

lang:uc( s )

Convertit la chaine en majuscules, en respectant les règles particulières de la langue correspondante.

Quand la bibliothèque ustring est chargée, la fonction mw.ustring.upper() est codée en appelant mw.language.getContentLanguage():uc( s ).

mw.language:ucfirst

lang:ucfirst( s )

Convertit le premier caractère de chaine en majuscule, comme le fait lang:uc().

mw.language:caseFold

lang:caseFold( s )

Convertit la chaine en une forme appropriée pour une comparaison non sensible à la casse. Notez que le résultat peut ne pas avoir de sens s'il est affiché.

mw.language:formatNum

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

Formate un nombre en respectant le groupement des chiffres et le séparateur décimal de la langue correspondante. Par exemple, « 123456.78 » produira « 123,456.78 », « 123 456,78 », ou même « ١٢٣٬٤٥٦٫٧٨ » selon la langue du wiki.

Une table options peut être fournit avec comme paramètre :

• noCommafy: true pour omettre les séparateurs de milliers et utiliser un point (.) en tant que séparateur décimal.

Des transformation numériques peuvent toujours avoir lieu, y compris le changement du séparateur décimal.

mw.language:formatDate

lang:formatDate( format, timestamp, local )

Formate une date selon le format indiqué dans la chaine format. Si timestamp est omis, l'heure actuelle est utilisée. La valeur local doit être un booléen ou nil. Si local est vrai, l'heure est formatée à partir de l'heure locale du wiki plutôt qu'à partir de l'heure UTC.

La chaine de formatage et les valeurs prises en charge pour timestamp sont identiques à celles de la fonction d’analyse syntaxique #time de l’Extension:ParserFunctions . Notez que les barres obliques inverses ("\") doivent parfois être doublées en Lua alors que ce n’est pas nécessaire en wikicode (car il s’agit d’un caractère d’échappement en Lua mais pas en wikicode) :

-- ceci génère un retour à la ligne alors que {{#time:\n}} affiche un "n"
lang:formatDate( '\n' )

-- ceci affiche un "n" alors que {{#time:\\n}} affiche un "\" suivi du numéro du mois.
lang:formatDate( '\\n' )

-- Ceci est équivalent à {{#time:\\n}} et non {{#time:\\\\n}}.
lang:formatDate( '\\\\n' )

mw.language:formatDuration

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

Découpe une durée (exprimée en secondes) dans des unités utilisables par l'homme, par exemple : 12345 en 3 heures, 25 minutes et 45 secondes, retournant le résultat dans une chaine.

chosenIntervals, s'il est fourni, est un tableau avec des valeurs nommant les unités d'intervalle à utiliser dans la réponse. Ceux-ci incluent 'millénaires', 'siècles', 'décennies', 'années', ' semaines', 'jours', 'heures', 'minutes' et 'secondes '.

mw.language:parseFormattedNumber

lang:parseFormattedNumber( s )

Prend un nombre formaté par lang:formatNum() et retourne le nombre correspondant. C'est une version « compatible avec les conventions de la langue » de tonumber().

mw.language:convertPlural

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

Permet de choisir la forme grammaticale adaptée depuis formes (qui doit être une séquence) ou ... en se basant sur le nombre n. Par exemple, vous pouvez utiliser n .. ' ' .. lang:plural( n, 'caillou', 'cailloux' ) ou n .. ' ' .. lang:plural( n, { 'caillou', 'cailloux' } ) pour générer un texte grammaticalement correct qu'il y ait 1 ou 200 "cailloux".

Le nombre de valeurs nécessaires pour la séquence dépend de la langue ; voir Internationalisation des mots magiques et PLURAL sur la FAQ de TranslateWiki.

mw.language:convertGrammar

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

Notez l'ordre différent des paramètres dans les deux versions. convertGrammar utilise le même ordre de paramètres que la méthode de même nom dans l'objet Language de MediaWiki alors que grammar utilise le même ordre de paramètres que la fonction parseur de même nom (voir Internationalisation des mots magiques).

Permet de choisir la forme correcte de mot en fonction de declinaison.

Les valeurs possibles pour mot et case dépendent de la langue, voir Help:Magic words/fr#Internationalisation et translatewiki:Grammar pour plus de détails.

mw.language:gender

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

Permet de choisir la chaine correspondante à genre, qui peut être 'male', 'female' ou un nom d'utilisateur.

mw.language:getArrow

lang:getArrow( direction )

Retourne un caractère Unicode correspondant direction :

• 'forwards' : → ou ← selon l'orientation de la langue
• 'backwards' : ← or → selon l'orientation de la langue
• 'left' : ←
• 'right' : →
• 'up' : ↑
• 'down' : ↓

mw.language:getDir

lang:getDir()

Retourne 'ltr' (left-to-right → de gauche à droite) ou 'rtl' (right-to-left ← de droite à gauche), selon la direction de la langue.

mw.language:getDirMark

lang:getDirMark( opposite )

Retourne une chaine contenant soit U+200E (le symbole d'écriture de gauche à droite) soit U+200F (le symbole de l'écriture de droite à gauche), selon la direction de la langue et selon que opposite est vrai ou faux (si vrai retourne la direction opposée à celle de la langue).

mw.language:getDirMarkEntity

lang:getDirMarkEntity( opposite )

Retourne '‎' or '‏', selon la direction de la langue et selon que opposite est vrai ou faux (si vrai retourne la direction opposée à celle de la langue).

mw.language:getDurationIntervals

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

Découpe une durée exprimée en secondes en unités lisibles par l'homme, et retourne le résultat dans une table dont les éléments sont classés par unité. Par exemple 12345 retournera les éléments 3 heures, 25 minutes et 45 secondes.

chosenIntervals, s'il est fourni, est un tableau avec des valeurs nommant les unités d'intervalle à utiliser dans la réponse. Ceux-ci incluent 'millénaires', 'siècles', 'décennies', 'années', ' semaines', 'jours', 'heures', 'minutes' et 'secondes '.

Ces mots-clés d'unités sont aussi les clés utilisées dans le tableau en réponse. Seules les unités ayant une valeur différente de zéro sont définies dans la réponse, â moins que la réponse serait vide, auquel cas on retourne l'unité la plus petite avec une valeur de 0.

Bibliothèque des messages

Cette bibliothèque est une interface aux versions localisées des messages et à l'espace de noms MediaWiki:.

Les fonctions documentées sous la forme mw.message.name sont disponibles dans la table globale mw.message. Les fonctions documentées sous la forme mw.message:name et msg:nom sont des méthodes d'un objet Message (voir mw.message.new).

mw.message.new

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

Crée un nouvel objet message pour le message clef. Les paramètres restants sont passés à la méthode du nouvel objet params() .

L'objet message n'a aucune propriété mais de nombreuses méthodes documentées ci-dessous.

mw.message.newFallbackSequence

mw.message.newFallbackSequence( ... )

Crée un nouvel objet message pour les messages indiqués (le premier qui existe sera utilisé).

L'objet message n'a aucune propriété mais de nombreuses méthodes documentées ci-dessous.

mw.message.newRawMessage

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

Crée un nouvel objet message en utilisant le texte indiqué plutôt qu'en cherchant un message internationalisé. Les paramètres additionnels sont passés à la méthode params() du nouvel objet.

L'objet message n'a aucune propriété mais de nombreuses méthodes documentées ci-dessous.

mw.message.rawParam

mw.message.rawParam( value )

Traite la valeur de façon qu'elle ne soit pas interprétée comme du wikitexte par msg:parse().

mw.message.numParam

mw.message.numParam( value )

Traite la valeur de façon à ce qu'elle soit automatiquement formatée comme par mw.language.getContentLanguage():formatNum(). Notez que ceci ne dépend pas de la bibliothèque language actuellement disponible dans Scribunto.

mw.message.getDefaultLanguage

mw.message.getDefaultLanguage()

Renvoie un objet Language pour la langue courante.

mw.message:params

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

Ajoute des paramètres au message, qui peuvent être passés en tant que paramètres individuels ou dans une séquence. Les paramètres doivent être des nombres, chaines ou des valeurs spéciales retournées par mw.message.numParam() ou mw.message.rawParam(). Si une table séquence est utilisée, les paramètres doivent être directement présents dans la table ; les références utilisant la méta-méthode __index ne marcheront pas.

Renvoie l'objet msg pour autoriser les appels chaînés.

mw.message:rawParams

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

Comme :params() mais chaque paramètre est passé préalablement par mw.message.rawParam().

Renvoie l'objet msg pour autoriser les appels chainés.

mw.message:numParams

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

Comme :params() mais chaque paramètre est passé préalablement par mw.message.numParam().

Renvoie l'objet msg pour autoriser les appels chainés.

mw.message:inLanguage

msg:inLanguage( lang )

Précise la langue à utiliser pour traiter le message. lang peut être une chaine ou une table avec une méthode getCode() (par exemple un objet Language).

La langue par défaut est celle retournée par mw.message.getDefaultLanguage().

Renvoie l'objet msg pour autoriser des appels chaînés.

mw.message:useDatabase

msg:useDatabase( bool )

Précise s'il faut chercher les messages dans l'espace de noms MediaWiki: (donc regarder dans la base de données) ou seulement utiliser les messages par défaut distribués avec MediaWiki.

La valeur par défaut est true.

Renvoie l'objet msg pour autoriser des appels chaînés.

mw.message:plain

msg:plain()

Remplace les paramètres et renvoie le message tel quel en wikicode. Les appels aux modèles et à des fonctions d'analyse syntaxique sont laissés intacts.

mw.message:exists

msg:exists()

Renvoie un booléen indiquant si la clé du message existe.

mw.message:isBlank

msg:isBlank()

Renvoie un booléen indiquant si la clé du message correspond à un contenu. Retourne true si la clé n'existe pas ou si le message est la chaîne vide.

mw.message:isDisabled

msg:isDisabled()

Renvoie un booléen indiquant si la clé de message est désactivée. Renvoie true si la clé n'existe pas, si le message est la chaîne vide ou la chaîne -.

Bibliothèque site

mw.site.currentVersion

Une chaine contenant la version actuelle de MediaWiki.

mw.site.scriptPath

La valeur de $wgScriptPath .

mw.site.server

La valeur de $wgServer

mw.site.siteName

La valeur de $wgSitename

mw.site.stylePath

La valeur de $wgStylePath

mw.site.namespaces

Table contenant les informations sur tous les espaces de noms, indexés par leur numéro.

Les données disponibles sont :

• id: * $1 : numéro de l'espace de noms ;
• name: * $1 : nom local de l'espace de noms ;
• canonicalName: Nom de l'espace de noms canonique.
• displayName: S'installer sur l'espace de noms 0, le nom à utiliser pour l'affichage (puisque le nom est souvent la chaîne vide).
• hasSubpages: Si les sous-pages sont activées pour l'espace de noms.
• hasGenderDistinction: Si l'espace de noms a des alias différents pour les différents genres.
• isCapitalized: Si la première lettre des pages dans l'espace de noms est capitalisée.
• isContent: Si c'est un espace de noms dédié à du contenu.
• isIncludable: Si les pages dans l'espace de noms peuvent être transcludées.
• isMovable: Si les pages dans l'espace de noms peuvent être déplacées.
• isSubject: Si c'est un espace de noms de sujet.
• isTalk: Si c'est un espace de noms dédia à de la conversation.
• defaultContentModel: Le modèle de contenu par défaut de l'espace de noms, en tant que chaîne de caractères.
• aliases: Liste des alias pour l'espace de noms.
• subject: Référence aux données de l'espace de noms du sujet correspondant.
• talk: Référence aux données de l'espace de noms dédié à de la conversation correspondant.
• associated: Référence aux données de l'espace de noms associé.

Une méta-table est présente pour permettre de chercher un espace de noms par son nom (localisé ou générique). Par exemple, mw.site.namespaces[4] et mw.site.namespaces.Project renverrons les informations concernant l'espace de noms du Projet.

mw.site.contentNamespaces

Table contenant uniquement les espaces de nom de contenu, indexés par leur numéro. Voir mw.site.namespaces.

mw.site.subjectNamespaces

Table contenant uniquement les espaces de nom de sujets, indexés par leur numéro. Voir mw.site.namespaces.

mw.site.talkNamespaces

Table contenant uniquement les espaces de nom de discussion, indexé par leur numéro. Voir mw.site.namespaces.

mw.site.stats

Table contenant les statistiques du site. Les éléments disponibles sont :

• pages: Nombres de pages dans le wiki.
• articles: Nombre d'articles dans le wiki.
• files: Nombre de fichiers dans le wiki.
• edits: Nombre de modifications dans le wiki.
• users: Nombre d'utilisateur dans le wiki.
• activeUsers: Nombre d'utilisateurs actifs dans le wiki.
• admins: Nombre d'utilisateurs dans le groupe "sysop" dans le wiki.

mw.site.stats.pagesInCategory

mw.site.stats.pagesInCategory( catégorie, qui )

Cette fonction est couteuse

Fournit les statistiques sur la catégorie. Si which a la valeur spéciale "*", le résultat est une table avec les propriétés suivantes :

• all: Total des pages, fichiers et sous-catégories.
• subcats: Nombre de sous-catégories
• files: Nombre de fichiers.
• pages: Nombre de pages.

Si type est l’une des clés en anglais ci-dessus ('all', 'subcats', 'files', 'pages') seul le nombre correspondant (tout, seulement les sous-catégories, seulement les fichiers, seulement les pages) est retourné.

Chaque appel à cette fonction incrémente le compteur de « fonctions couteuses ».

mw.site.stats.pagesInNamespace

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

Renvoie le nombre de pages dans l'espace de noms indiqué (indiqué par son numéro).

mw.site.stats.usersInGroup

mw.site.stats.usersInGroup( groupe )

Renvoie le nombre d'utilisateurs dans le groupe indiqué.

mw.site.interwikiMap

mw.site.interwikiMap( filtre )

Retourne une table contenant les préfixes interwiki disponible. Si filtre est "local", alors uniquement les données pour les préfixes interwiki locaux sont retournées. Si filtre est "!local", alors uniquement les données pour les préfixes interwiki non-locaux sont retournées. Si aucun filtre n'est spécifié, alors les données pour tous les préfixes sont retournées. Un préfixe "local" dans ce context est un qui est pour le même projet. Par exemple, sur Wikipedia en français, les Wikipedias dans d'autres langues sont considérés comme locaux, alors que le Wikitionnaire ne l'est pas.

Les clés de la table retournée sont les préfixes interwiki (par exemple 'en' ou 'commons') et les valeurs sont des sous-tables avec les propriétés suivantes :

• prefix - le préfixe interwiki.
• url - l'URL à laquelle l'interwiki pointe. Le nom de la page est représenté par le paramètre $1.
• isProtocolRelative - un booléen montrant si l'IRL est protocol-relative.
• isLocal - si l'URL est destinée à un site de ce projet.
• isCurrentWiki - si l'URL est pour le wiki actuel.
• isTranscludable - si les pages utilisant ce préfixe interwiki sont transcludable. Cela requière de la transclusion effrayante, qui est désactivée sur les wikis Wikimedia.
• isExtraLanguageLink - si l'interwiki est répertorié dans $wgExtraInterlanguageLinkPrefixes .
• displayText - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the display text shown for the interlanguage link. Nil if not specified.
• tooltip -

for links listed in $wgExtraInterlanguageLinkPrefixes, this is the tooltip text shown when users hover over the interlanguage link. Nil if not specified.

Bibliothèque text

La bibliothèque text fournit quelques fonctions utiles de traitement de texte absentes des bibliothèques string et ustring. Ces fonctions peuvent fonctionner avec les caractères UTF-8.

mw.text.decode

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

Remplace les entités HTML de la chaine par les caractères correspondant.

Si le booléen decodeNamedEntities est absent ou vaut false, les seules entités nommées reconnues sont $2/code (<), $3 (>), & (&), " (") et $4 (l'espace insécable U+00A0). Sinon la liste des entités HTML5 nommées à reconnaître est chargée par la fonction [$url get_html_translation_table] de PHP.

Bogues connus : environ 600 des 2 200 entités nommées du standard HTML5 ne sont pas décodées, même si decodeNamedEntities est utilisé; cela inclut approximativement 40 des 250 entités également incluses dans HTML4. Cela se produit car la fonction get_html_translation_table de PHP renvoie seulement une correspondance par caractère, donc par exemple → n'est pas décodé car PHP renvoie seulement → correspondant à →.

mw.text.encode

mw.text.encode( string )
mw.text.encode( string, charset )

Remplace les caractères de la chaîne par des entités HTML. Cinq caractères sont remplacés par l'entité nommée correspondante : <, >, &, " et l'espace insécable (U+00A0). Tous les autres sont remplacés par des entités numériques.

Si charset est fourni, il doit être une chaîne pouvant être utilisée à l'intérieur des crochets d'un motif Ustring, par exemple set dans [set]. Par défaut, l'ensemble contient six caractères : <, >, &, ", ' ainsi que l'espace insécable (U+00A0).

mw.text.jsonDecode

mw.text.jsonDecode( string )
mw.text.jsonDecode( string, flags )

Décode une chaine JSON. flags peut être 0, mw.text.JSON_PRESERVE_KEYS,mw.text.JSON_TRY_FIXING ou une combinaison de ces valeurs (en utilisant l’opérateur +).

Normalement les tableaux JSON qui commencent à l'indice 0 sont renuméroté suivant la norme LUA en table séquence partant de l'indice 1. Pour désactiver ce comportement utiliser mw.text.JSON_PRESERVE_KEYS.

Pour être tolérant par rapport aux erreurs JSON, comme les virgules après le dernier élément dans les tableaux ou objets, utiliser mw.text.JSON_PRESERVE_KEYS. Ceci est déconseillé.

Limitations :

• les tableaux JSON décodées ne sont pas forcément des séquences en Lua si le tableau contient des valeurs nulles ;
• les clés ayant des valeurs nulles dans les objets JSON seront perdues ;
• il n'est pas directement possible de dire si une table Lua était un tableau ou un objet JSON avec des clés numériques séquentielles ;
• un objet JSON avec des clés numériques séquentielles commençant à 1 sera décodé en une structure identique à un tableau avec les mêmes valeurs (sauf si mw.text.JSON_PRESERVE_KEYS est utilisé), alors que ce n'est pas du tout la même chose en JSON.

mw.text.jsonEncode

mw.text.jsonEncode( value )
mw.text.jsonEncode( value, flags )

Transforme la valeur en chaine JSON. Génère une erreur si valeur ne peut pas être codé en JSON. flags peut être 0, mw.text.JSON_PRESERVE_KEYS, mw.text.JSON_PRETTY, ou une combinaison de ces valeurs (utiliser l'opérateur +).

Normalement les tables séquence Lua qui commencent à l'indice 1 sont transformées en tableaux JSON partant de l'indice 0. Si mw.text.JSON_PRESERVE_KEYS est activé dans flags, seules les tables séquences avec une clé 0 seront transformée en tableaux JSON.

Limitations :

• les tables vides sont toujours codées comme des tableaux vides ([]), jamais comme des objets ({}) ;
• les séquence ne peuvent pas être encodé en objet JSON sans ajouter un élément factice ;
• pour générer des objets ou tableaux avec des valeurs nulles une implémentation délicate de la méta-méthode __pairs est nécessaire ;
• une table Lua ayant des clés numérique séquentielles commençant à 0 sera codé en tableau JSON comme une séquence commençant à l'indice 1, sauf si mw.text.JSON_PRESERVE_KEYS est utilisé ;
• lorsqu'une table contient une clé numérique et une clé sous forme de chaine représentant le même nombre, le comportement n'est pas spécifié.

mw.text.killMarkers

mw.text.killMarkers( string )

Retire d'une chaine toutes les balises spécifiques à MediaWiki.

mw.text.listToText

mw.text.listToText( list )
mw.text.listToText( list, separator, conjunction )

Joint une liste sous forme « textuelle ». Fait la même chose que table.concat() mais avec un séparateur différent pour l'élément final.

Le séparateur par défaut est récupéré depuis la version de MediaWiki:comma-separator dans la langue de contenu du wiki, et la conjonction par défaut est issue du message MediaWiki:and concaténé avec MediaWiki:word-separator.

Exemples, avec les valeurs par défaut des messages en français :

 -- renvoie une chaine vide
 mw.text.listToText( {} )
 
 -- renvoie '1'
 mw.text.listToText( { 1 } )
 
 -- renvoie '1 et 2'
 mw.text.listToText( { 1, 2 } )
 
 -- renvoie '1, 2, 3, 4 et 5'
 mw.text.listToText( { 1, 2, 3, 4, 5 } )
 
 -- renvoie '1; 2; 3; 4 or 5'
 mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' or ' )

mw.text.nowiki

mw.text.nowiki( string )

Remplace divers caractères dans la chaine par des entités HTML pour éviter leur interprétation comme wikitexte. Ceci comprend :

• les caractères suivants : ", &, ', <, =, >, [, ], {, |, } ;
• les caractères suivants au début de la chaine ou juste après un retour à la ligne : #, *, :, ;, espace, tabulation (\t) ;
• les lignes vides auront l'un des caractères de saut de ligne (LF) ou de retour chariot (CR) associés échappé ;
• ---- au début de la chaine ou juste après un saut de ligne verra son premier - échappé ;
• __ aura un tiret bas d'échappé ;
• :// aura le deux-points échappé ;
• Un espace blanc suivant ISBN, RFC, ou PMID sera échappé.

• The following characters at the start of the string or immediately after a newline: #, *, :, ;, space, tab (\t)

• Blank lines will have one of the associated newline or carriage return characters escaped

• ---- at the start of the string or immediately after a newline will have the first - escaped

• __ will have one underscore escaped

• :// will have the colon escaped

• A whitespace character following ISBN, RFC, or PMID will be escaped

mw.text.split

mw.text.split( string, pattern, plain )

Découpe une chaine en sous-chaines dont les limites correspondent au motif Ustring motif. Si normal est présent et vrai, motif est interprété comme une chaine littérale et non comme un motif Lua (comme le paramètre de même nom pour mw.ustring.find()). Retourne une table contenant les sous-chaines.

Par exemple mw.text.split( 'a b\tc\nd', '%s' ) retourne une table { 'a', 'b', 'c', 'd' }.

Si motif correspond à la chaine vide, s sera découpé en caractères individuels.

Note that this function can be over 60 times slower than a reimplementation that is not Unicode-aware, such as the following:

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
    		-- Empty separator!
    		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( string, pattern, plain )

Retourne une fonction itérative qui va itérer sur les sous-chaines qui auraient été retournées par un appel équivalent à mw.text.split().

Note that this function can be over 60 times slower than a reimplementation that is not Unicode-aware, such as the following:

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
				-- Empty separator!
				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 = string, attrs = table, content = string|false }

Notez l'utilisation de paramètres nommés.

Génère un tag à la façon HTML pour nom.

Si attributs est indiqué, il doit être une table avec des clés de type chaine. Les valeurs de ces clés sont utilisées comme valeurs des attributs. Une valeur booléenne true insère un paramètre HTML5 sans valeur, et false ignore le paramètre. Toute autre valeur génère une erreur.

Si contenu n'est pas présent (ou vaut nil), seul le tag ouvrant est retourné. Si content vaut false, un tag auto-fermant est retourné. Sinon il doit être un nombre ou une chaine auquel cas ce contenu est inséré entre l'ouverture et la fermeture du tag. Notez que le contenu n'est pas automatiquement encodé en HTML ; utiliser mw.text.encode() au besoin.

Pour retourner proprement un tag comme ‎<ref>, utilisez plutôt frame:extensionTag().

mw.text.trim

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

Enlève les espaces et autres caractères au début et à la fin d'une chaine.

Si charset est indiqué, il doit être une chaine syntaxiquement compatible avec les classes de caractères des motifs Ustring, i.e. le « set » dans [set]. Par défaut : les espacements ASCII, %s, ce qui est équivalent à '\t\r\n\f\v '.

mw.text.truncate

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

Tronque texte à la longueur indiquée, en ajoutant suspension si une troncature est effectuée. Si longueur est positif, la fin de la chaine est tronquée ; s'il est négatif, c'est le début de la chaine qui est enlevé. Si adjusteLongueur est présent et vrai, le résultat en incluant suspension ne sera pas plus long que la longueur précisée.

La valeur par défaut pour suspension est issue de la version du message MediaWiki:ellipsis dans la langue du contenu du wiki.

Exemples utilisant ... pour suspension (valeur par défaut) :

-- Renvoie « foobarbaz »
mw.text.truncate( "foobarbaz", 9 )

-- Renvoie « fooba... »
mw.text.truncate( "foobarbaz", 5 )

-- Renvoie « ...arbaz »
mw.text.truncate( "foobarbaz", -5 )

-- Renvoie « foo... »
mw.text.truncate( "foobarbaz", 6, nil, true )

-- Renvoie « foobarbaz » car c'est plus rapide que « foobarba... »
mw.text.truncate( "foobarbaz", 8 )

mw.text.unstripNoWiki

mw.text.unstripNoWiki( string )

Remplace les strip markers <nowiki> par la chaine d'origine. Les autres strip markers ne sont pas modifiés.

mw.text.unstrip

mw.text.unstrip( string )

Équivalent à mw.text.killMarkers( mw.text.unstripNoWiki( s ) ).

Ceci ne révèle plus le code HTML liés à certaines balises comme <ref>, contrairement aux anciennes versions de Scribunto.

Bibliothèque title

mw.title.equals

mw.title.equals( a, b )

Teste si deux titres sont égaux. Notez que les fragments sont ignorés lors des comparaisons.

mw.title.compare

mw.title.compare( a, b )

Retourne -1, 0 ou 1 selon que le titre a est plus petit, égal ou supérieur au titre b

Cette comparaison s'effectue d'abord sur le préfixe interwiki (si présent) par ordre alphabètique, puis par numéro de namespace, et enfin alphabétiquement sur le texte du titre lui-même. La comparaison de chaine utilise l'opérateur < standard de Lua.

mw.title.getCurrentTitle

mw.title.getCurrentTitle()

Retourne un objet title pour la page courante.

mw.title.new

mw.title.new( text, namespace )
mw.title.new( ID )

Cette fonction est couteuse lorsqu'elle est appelée avec un id

Crée un nouvel objet title.

Si un nombre id est indiqué, un objet est créé pour la page ayant cet identifiant. Le titre référencé sera compté comme lié depuis la page courante. Si aucune page n'a d'identifiant, retourne nil. Le compteur de « fonctions couteuses » sera incrémenté pour chaque objet créé, à part pour la page courante ou pour un titre déjà chargé.

Si une chaine texte est indiquée à la place, un objet est créé pour ce titre (même si la page correspondante n'existe pas). Si texte ne précise pas d'espace de noms, namespace (qui peut être toute clé se trouvant dans mw.site.namespaces) sera utilisé. Si texte n'est pas un titre valide, nil est retourné.

mw.title.makeTitle

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

Crée un objet title avec pour titre titre dans l'espace de noms namespace, éventuellement avec le fragment spécifié et le préfixe interwiki. namespace peut être n'importe quelle clé trouvée dans mw.site.namespaces. Si le titre résultant n'est pas valide, renvoie nil.

Notez que cette fonction utilise toujours namespace, contrairement à mw.title.new(). Par exemple mw.title.makeTitle( 'Catégorie', 'Module:Foo' ) crée un objet pour la page « Catégorie:Module:Foo » alors que mw.title.new( 'Module:Foo', 'Catégorie' ) crée un objet pour la page « Module:Foo ».

Notez aussi que la fonctionnalité pour les titres interwiki est limitée à interwiki / isExternal / isLocal et aux méthodes relatives aux URLs; les autres méthodes peuvent avoir un comportement inattendu.

Objet title

Un objet title a de nombreuses propriétés et méthodes, la plupart étant en lecture seule.

Notez que les champs se terminant par Text retournent les titres sous forme de chaines, tandis que les champs se terminant par Title retournent des objets title.

• id : l'identifiant de la page. Vaut 0 si la page n'existe pas.

Cela peut être couteux.

• interwiki : le préfixe interwiki ou une chaine vide si aucun.
• namespace : le numéro d'espace de noms.
• fragment : le fragment (alias lien section/ancre), ou la chaîne vide. Peut être attribué.
• nsText : le nom local de l'espace de noms de la page.
• subjectNsText : le nom de l'espace de noms sujet de la page.

• talkNsTest : le texte de l’espace de nom de discussion pour la page, ou nil si le titre ne peut pas avoir de page de discussion. (ajouté dans MediaWiki 1.42.0-wmf.15)

• text : le titre de la page, sans l'espace de noms ni les préfixes interwiki.
• prefixedText : le titre de la page, avec espace de noms et interwiki.
• fullText : le titre de la page, avec l'espace de noms, l'interwiki et le fragment (l’interwiki n’est pas retourné si identique à celui actuel).

• rootText : si c'est une sous-page, le titre de la page de base sans préfixe. Sinon identique à title.text.

• baseText : si c'est une sous-page, le titre de la page dont on est la sous-page, sans préfixe. Sinon identique à title.text.

• subpageText : si c'est une sous-page, juste le nom de la sous-page. Sinon identique à title.text.

• canTalk : indique si la page peut avoir une page de discussion.
• exists : indique si la page existe. Alias pour file.exists pour les médias. Pour l'espace de noms Fichiers c’est l'existence de la description du fichier qui est vérifiée, pas celle du fichier lui-même. Cela peut être couteux
• file, fileExists : voir ci-dessous ;
• isContentPage: vrai si le titre est dans un espace de noms de contenu.
• isExternal: vrai si le titre a un préfixe interwiki.
• isLocal: vrai si le titre est dans le même projet que le script. Par exemple, sur la Wikipédia en anglais, toutes les autres Wikipédias sont considérées comme local alors que le Wiktionaire ne l’est pas.
• isRedirect : vrai si la page est une redirection (peut être couteux) ;
• isSpecialPage : vrai si la page est dans l’espace de noms "Spécial:" ;
• isSubpage : vrai si la page est une sous-page ;
• isTalkPage : vrai s’il s’agit du titre d’une page de discussion ;
• isSubpageOf( titre2 ) : vrai si la page est une sous-page de titre2 ;

• inNamespace( ns ) : vrai si la page est dans l'espace de noms indiqué (ns peut être toute clé trouvée dans mw.site.namespaces) ;

• inNamespaces( ... ) : vrai si la page est dans l’un des espaces de nom indiqués (les espaces de noms peuvent être toute clé trouvée dans mw.site.namespaces) ;

• hasSubjectNamespace( ns ) : vrai si l’espace de noms sujet de la page est dans l'espace de noms indiqué. (ns peut être toute clé trouvée dans mw.site.namespaces) ;

• contentModel : le type de contenu pour ce titre, sous forme de chaine (peut être coûteux) ;

• basePageTitle : identique à mw.title.makeTitle( title.namespace, title.baseText ) ;

• rootPageTitle : identique à mw.title.makeTitle( title.namespace, title.rootText ) ;

• talkPageTitle : identique à mw.title.makeTitle( mw.site.namespaces[title.namespace].talk.id, title.text ), ou nil si la page ne peut pas avoir de page de discussion ;

• subjectPageTitle : identique à mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text ) ;

• redirectTarget : retourne un objet title correspondant à la cible de la redirection si la page est une redirection que cette page existe, false dans les autres cas ;

• protectionLevels : les niveaux de protection de la page. C'est une table dont les clés correspondent à chaque action ("edit" et "move"). Les valeurs de la table sont des tableaux, le premier élément de chacun d'entre eux étant une chaine contenant le niveau de protection. Si la page n'est pas protégée, soit les valeurs de la table, soit les éléments du tableau vaudront nil. Ceci est coûteux.

• cascadingProtection: protections en cascade applicables à la page. C'est un tableau avec des clés "restrictions" (elles-mêmes étant un tableau de clés telles que celles de protectionLevels) et "sources" (un tableau contenant les titres de où les protections découlent en cascade). Si aucune protection n'arrive en cascade sur la page, "restrictions" et "sources" seront vides. Ceci est coûteux.

• subPageTitle( text ) : identique à mw.title.makeTitle( title.namespace, title.text .. '/' .. text ) ;

• partialUrl() : retourne title.text encodé comme une URL.

• fullUrl( query, proto ) : Retourne l'URL complète de la page (avec optionnellement un query, une chaine ou une table). proto est optionnel et permet de préciser "http", "https", "relative" (par défaut), ou "canonical" ;

• localUrl( query ) : retourne l'URL locale de la page (avec optionnellement un query, une chaine ou une table) ;
• canonicalUrl( query ) : retourne l'URL canonique de la page (avec optionnellement un query, une chaine ou une table) ;

• getContent() : retourne le contenu non interprété de la page, ou nil si elle n'existe pas (mais pour transclure ses modèles utiliser frame:expandTemplate{ title = ':' .. nom_de_page }). La page sera enregistré comme une transclusion.

• pageLang: A language object for the title's page content language, which defaults to the wiki's content language. This is expensive.

Les objets title peuvent être comparés en utilisant les opérateurs relationnels. tostring( title ) retourne title.prefixedText.

Sachez qu’accéder à n’importe quel champ couteux d’un objet title enregistre un « lien » vers la page (visible sur Spécial:Pages liées, entre autres). Utiliser la méthode getContent() d’un objet title ou accéder au champ redirectTarget enregistre une « inclusion » et accéder aux champs file ou fileExists d’un objet title enregistre un « lien vers le fichier ».

Métadonnées des fichiers

Les objets title représentants des pages dans l’espace de noms Fichier ou Média auront une propriété appelée file. Celle-ci est couteuse. Il s’agit d’une table avec la structure suivante :

• exists : indique si le fichier existe. Sera enregistré comme une utilisation du fichier. La propriété fileExists de l'objet title existe pour des raisons de rétro-compatibilité et est un alias de cette propriété. Si false, toutes les autres propriétés de file seront nil ;

• width : la largeur du fichier. Si le fichier contient plusieurs pages, c'est la largeur de la première page ;
• height : la hauteur du fichier. Si le fichier contient plusieurs pages, c'est la hauteur de la première page ;

• pages : si le format du fichier permet d'avoir plusieurs pages, c'est une table contenant une sous-table pour chaque page du fichier (nil sinon). L’opérateur # peut être utilisé pour connaitre le nombre de page du fichier. Les sous-tables contiennent les propriétés width et height avec la largeur et la hauteur de la page ;

• size : la taille du fichier en octets ;

• mimeType : le MIME type du fichier.

• length : la longueur (durée) du fichier multimédia en secondes. Zéro pour les types de médias qui ne prennent pas en charge la longueur.

Propriétés coûteuses

Les propriétés id, isRedirect, exists, et contentModel nécessitent d'aller chercher les données à propos de ce titre dans la base de donnée. Pour cette raison le compteur de fonctions coûteuses est incrémenté la première fois que l'une d'elles est utilisée pour un titre différent de la page en cours. Les accès suivants à ces propriétés pour la même page n'incrémenteront pas le compteur.

Les autres propriétés indiquées comme coûteuses incrémenteront systématiquement le compteur de fonctions coûteuses la première fois qu'elles sont utilisées pour une page autre que la page en cours.

Bibliothèque uri

mw.uri.encode

mw.uri.encode( string, enctype )

Encode la chaine s au format URL. Le type par défaut 'QUERY' encode les espaces en utilisant +, 'PATH' les encode en utilisant %20 et 'WIKI' les encode en utilisant _.

Notez que le format 'WIKI' n'est pas entièrement réversible puisque les espaces et les underscores ("_") sont encodés de la même façon.

mw.uri.decode

mw.uri.decode( string, enctype )

Décode la chaine s. Le type par défaut 'QUERY' décode les + en espaces, 'PATH' décode les %20 en espaces et 'WIKI' décode les _ en espaces.

mw.uri.anchorEncode

mw.uri.anchorEncode( string )

Encode la chaine pour être utilisée en tant que fragment MediaWiki.

mw.uri.buildQueryString

mw.uri.buildQueryString( table )

Encode une table en tant que chaine de requête. Les clés doivent être des chaines. Les valeurs peuvent être des chaines, des nombres, des séquences ou false.

mw.uri.parseQueryString

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

Décode une chaine correspondant à une requête en une table. Les clés qui dans la chaine n'ont aucune valeur prendront la valeur false ; les clés répétées de multiples fois auront pour valeur des séquences ; les autres auront pour valeur des chaines.

Les paramètres numériques optionnels i et j peuvent être utilisés pour indiquer qu’une sous-chaine de s doit être traitée, et pas la chaine en entier. i est la position du premier caractère de la sous-chaine et vaut 1 par défaut. j est la position du dernier caractère de la sous-chaine et vaut la longueur de la chaine par défaut. i et j peuvent tous les deux être négatifs, comme dans string.sub.

mw.uri.canonicalUrl

mw.uri.canonicalUrl( page, query )

Renvoie un URI object pour le canonique URL pour une page, avec une chaîne/table de requête facultative.

mw.uri.fullUrl

mw.uri.fullUrl( page, query )

Renvoie un URI object pour full URL pour une page, avec une chaîne/table de requête facultative.

mw.uri.localUrl

mw.uri.localUrl( page, query )

Renvoie un URI object pour local URL pour une page, avec une chaîne/table de requête facultative.

mw.uri.new

mw.uri.new( string )

Construit un nouvel objet uri pour la chaine ou la table s. Voir la description d'un objet uri pour les champ possible de la table.

mw.uri.validate

mw.uri.validate( table )

Valide la table (ou l'objet uri). Retourne un booléen indiquant si la table est valide, et en cas d'échec une chaine décrivant les erreurs trouvées.

Objet uri

L'objet uri contient les champs suivants, dont certain ou tous peuvent valoir nil :

• protocol : chaine du protocole ;
• user : nom de l'utilisateur ;
• password : mot de passe ;
• host : nom de la machine ;
• port : numéro du port (entier) ;
• path : chemin ;
• query : une table comme dans mw.uri.parseQueryString ;
• fragment : le fragment.

Les propriétés suivantes sont également disponibles :

• userInfo: utilisateur et mot de passe ;
• hostPort: machine et numéro de port ;
• authority: les deux précédents ensembles ;
• queryString: version chaine de la table de requête ;
• relativePath: chemin, requête et fragment.

tostring() retourne la chaîne de l'uri.

Les méthodes de l'objet uri sont :

mw.uri:parse

uri:parse( string )

Analyse une chaine dans l'objet uir courant. Tout champ spécifié dans la chaine sera remplacé dans l'objet, les champs non spécifiés gardent leur ancienne valeur.

mw.uri:clone

uri:clone()

Crée une copie de l'objet uri.

mw.uri:extend

uri:extend( parameters )

Intègre la table parametres dans la table de requête de l'objet.

Bibliothèque ustring

La bibliothèque ustring est une ré-implémentation de la bibliothèque standard string, à la différence qu'elle peut opérer sur des caractères encodés en UTF-8.

La plupart des fonctions génèrent une erreur si la chaine n'est pas valide en codage UTF-8

mw.ustring.maxPatternLength

La taille maximum autorisée pour un motif (pattern), en octets.

mw.ustring.maxStringLength

La taille maximum autorisée pour une chaine, en octets.

mw.ustring.byte

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

Retourne les octets d'une chaine. Identique à string.byte().

mw.ustring.byteoffset

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

Retourne la position en octets dans la chaine du n^ième caractère de la chaine à partir de l'octet i. Par défaut n et i valent 1. i peut être négatif auquel cas l'octet de départ est compté à partir de la fin.

Le caractère n == 1 est le premier caractère commençant à ou après l'octet i ;
Le caractère n == 0 est le premier caractère commençant à ou avant l'octet i
Notez que cela peut-être le même caractère. Le caractère correspondant aux valeurs plus grandes ou plus petites de n sont relative à ces position.

mw.ustring.char

mw.ustring.char( ... )

Similaire à string.char(), mais les paramètre sont des points de codes Unicode et non des octets.

local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- value vaut dorénavant « Привет! »

mw.ustring.codepoint

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

Similaire à string.byte(), mais les valeurs retournées sont des points de code Unicode et les positions sont celles des caractères et non des octets.

mw.ustring.find

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

Similaire à string.find(), mais le motif est géré comme décrit dans motifs ustring et la position init est en caractères et non en octets.

mw.ustring.format

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

Identique à string.format(). Les tailles et précisions pour les chaines sont toujours en octets et non en points de code Unicode.

mw.ustring.gcodepoint

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

Retourne trois valeurs pour itérer sur les points de code Unicode de la chaine. i vaut 1 par défaut et j vaut -1 par défaut. Ça sert à être utilisé par la forme itérateur de for :

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

mw.ustring.gmatch

mw.ustring.gmatch( s, pattern )

Similaire à string.gmatch(), mais le motif est géré comme décrit dans motifs ustring.

Known bug - When used with a pattern which can match the empty string, the function will get stuck in an infinite loop. For example, the following loop never terminates:

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

mw.ustring.gsub

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

Similaire à string.gsub(), mais le motif est géré comme décrit dans motifs ustring.

Bogues connus: si repl est un tableau, on peut utiliser des nombres comme clé au lieu de chaînes de caractères (par exemple pour remplacer les instances de "5" dans une chaîne, la valeur pour la clé [5] ou ["5"] serait utilisée); en conséquence la sortie est imprévisible s'ils ont des valeurs différentes (non nulles). Ce n'est pas un problème pour string.gsub() qui ignore les clés numériques.

mw.ustring.isutf8

mw.ustring.isutf8( string )

Retourne true si la chaine est en UTF-8 valide, false sinon.

mw.ustring.len

mw.ustring.len( string )

Retourne la longueur de la chaine en point de code Unicode ou nil si la chaine n'est pas valide en UTF-8.

Voir string.len() pour une fonction similaire qui utilise la longueur en octets plutôt que des points de code.

mw.ustring.lower

mw.ustring.lower( string )

Similaire à string.lower() à part que la fonction suit le format Unicode.

Si la bibliothèque language est également chargée, ceci utilisera lc() sur la langue courante à la place.

mw.ustring.match

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

Similaire à string.match(), mais le motif est géré comme décrit dans motifs ustring et la position init est en caractères et non en octets.

mw.ustring.rep

mw.ustring.rep( string, n )

Identique à string.rep().

mw.ustring.sub

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

Similaire à string.sub(), mais les positions sont en caractères et non en octets.

mw.ustring.toNFC

mw.ustring.toNFC( string )

Convertit la chaîne en forme normalisée C (connu également comme composition canonique de la forme normalisée). Renvoie nil si la chaîne n'est pas un UTF-8 valide.

mw.ustring.toNFD

mw.ustring.toNFD( s )

Convertit la chaîne en forme normalisée D (connu également comme décomposition canonique de la forme normalisée). Renvoie nil si la chaîne n'est pas un UTF-8 valide.

mw.ustring.toNFKC

mw.ustring.toNFKC( s )

Convertit la chaîne en forme normalisée KC (connu également comme composition de compatibilité de la forme normalisée). Renvoie nil si la chaîne n'est pas un UTF-8 valide.

mw.ustring.toNFKD

mw.ustring.toNFKD( s )

Convertit la chaîne en forme normalisée KD (connu également comme décomposition de compatibilité de la forme normalisée). Renvoie nil si la chaîne n'est pas un UTF-8 valide.

mw.ustring.upper

mw.ustring.upper( s )

Similaire à string.upper() à part que la fonction suit le format Unicode.

Si la bibliothèque language est également chargée, ceci utilisera uc() sur la langue courante à la place.

Motifs ustring (pattern)

Les motifs dans les fonctions ustring utilisent la même syntaxe que celle des motifs de la bibliothèque string. La différence principale est que les classes de caractères sont redéfinis en terme de propriétés de caractères Unicode :

• %a : représente tous les caractères de la catégorie « Lettre » ;
• %c : représente tous les caractères de la catégorie « Contrôle » ;
• %d : représente tous les caractères de la catégorie « Nombre, chiffre décimal » ;
• %l : représente tous les caractères de la catégorie « Lettre minuscule » ;
• %p: représente tous les caractères de la catégorie « Ponctuation » ;
• %s : représente tous les caractères de la catégorie « Séparateur », plus la tabulation, le saut de ligne, le retour charriot, la tabulation verticale et le saut de page ;
• %u : représente tous les caractères de la catégorie « Lettre majuscule » ;
• %w : représente tous les caractères des catégories générales « Lettre » et « Nombre décimal » ;
• %x : ajoute la version en largeur complète des chiffres hexadécimaux.

Comme dans Modèles de bibliothèque de chaînes, %A, %C, %D, %L, %P, %S, %U, %W et %X représente ici l’ensemble complémentaire (« tous les caractères sans donnés dans la catégorie générale »).

Dans tous les cas, les caractères sont interprétés comme des caractères Unicode et non des octets, donc des séries comme [０-９], des motifs comme %b«», et des quantificateurs appliqués à des caractères multi-octets fonctionnent correctement. La capture vide capturera des positions en points de codes et non en octets.

Limitations connues : à la différence des motifs de la bibliothèque String, les motifs de la bibliothèque Ustring ont une longueur maximale de 10 000 octets. Si le motif excède cette longueur alors la fonction Ustring génèrera une erreur. Parce que la bibliothèque String a son propre maximum de 32 captures (à la différence de la bibliothèque Ustring), il n'est par conséquent pas possible d'utiliser un motif qui dépasserait ces deux limites, car il ne sera pas compatible avec les deux bibliothèques.

Note : 9 caractères ASCII, $, +, <, =, >, ^, `, |, ~, peuvent être détectés par %p dans la bibliothèque string, mais pas dans la bibliothèque ustring, car Unicode les classe comme des symboles plutôt que de la ponctuation.

Bibliothèques chargeables

Ces bibliothèques ne sont pas incluses par défaut, mais peuvent être chargées si besoin en utilisant require().

Bibliothèque bit32

Ceci est une émulation de la bibliothèque bit32 de Lua 5.2. On peut la charger avec :

 bit32 = require( 'bit32' )

La bibliothèque bit32 fournit des opérations binaires sur des entiers non signés 32bits. Les nombres en entrée sont tronqués en entiers (d'une façon non spécifiée) et ramenés entre 0 et 2³²−1 par une opération de modulo. Les valeurs retournées sont également dans cet intervalle de valeurs.

Quand les bits sont numérotés (comme dans bit32.extract()), 0 est le bit de poids faible (celui correspondant à la valeur 2⁰) et 31 est celui de poids fort (celui valant 2³¹).

bit32.band

bit32.band( ... )

Retourne le ET binaire (AND) de ses paramètres : le résultat a un bit donné à 1 si et seulement si le même bit de chaque paramètre est à 1.

Appelée sans paramètre, cette fonction retourne tous les bits à 1.

bit32.bnot

bit32.bnot( x )

Retourne le complément binaire (NOT) de x.

bit32.bor

bit32.bor( ... )

Retourne le OU binaire (OR) de tous ses paramètres : le résultat a un bit donné à 1 si au moins un des paramètres a le même bit à 1.

Appelée sans paramètre, cette fonction retourne tous les bits à 0.

bit32.btest

bit32.btest( ... )

Équivalent à bit32.band( ... ) ~= 0.

bit32.bxor

bit32.bxor( ... )

Retourne le OU EXCLUSIF binaire (XOR) de ses paramètres : le résultat a un bit donné à 1 si le nombre de paramètres ayant ce même bit à 1 est impair.

Appelée sans paramètre, cette fonction retourne tous les bits à 0.

bit32.extract

bit32.extract( n, field, width )

Extrait width bits de n, en commençant au bit field. Accéder à des bits en dehors de l'intervalle 0 à 31 est une erreur.

Si width est non précisé, sa valeur par défaut est 1.

bit32.replace

bit32.replace( n, v, field, width )

Remplace width bits de n, en commençant au bit field, avec les width premiers bits de v. Accéder à des bits en dehors de l'intervalle 0 à 31 est une erreur.

Si width est non précisé, sa valeur par défaut est 1.

bit32.lshift

bit32.lshift( n, disp )

Retourne le nombre n décalé de disp bits vers la gauche. Ceci est un décalage logique : les bits insérés valent 0. Ceci est en général équivalent à multiplier par 2^disp.

Notez qu'un déplacement au delà de 31 donne 0.

bit32.rshift

bit32.rshift( n, disp )

Retourne le nombre n décalé de disp bits vers la droite. Ceci est un décalage logique : les bits insérés valent 0. Ceci est en général équivalent à diviser par 2^disp.

Notez qu'un déplacement au delà de 31 donne 0.

bit32.arshift

bit32.arshift( n, disp )

Retourne le nombre n décalé de disp bits vers la droite. Ceci est un décalage arithmétique : si disp est positif, les bits insérés seront les mêmes que le bit 31 du nombre initial.

Notez qu'un déplacement au delà de 31 donne 0 ou 4294967295.

bit32.lrotate

bit32.lrotate( n, disp )

Retourne le nombre n décalé circulairement de disp bits vers la gauche.

Notez que les rotations sont équivalentes modulo 32 : une rotation de 32 est équivalent à une rotation de 0, une rotation de 33 à une rotation de 1, etc.

bit32.rrotate

bit32.rrotate( n, disp )

Retourne le nombre n décalé circulairement de disp bits vers la droite.

Notez que les rotations sont équivalentes modulo 32 : une rotation de 32 est équivalente à une rotation de 0, une rotation de 33 à une rotation de 1, etc.

Bibliothèque libraryUtil

Cette bibliothèque contient des méthodes utiles pour implémenter des bibliothèques Scribunto. Elle peut être chargée avec :

 libraryUtil = require( 'libraryUtil' )

libraryUtil.checkType

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

Génère une erreur si type( arg ) ne correspond pas à expectType. De plus, aucune erreur n'est générée si arg est nil et si nilOk est vrai.

name est le nom de la fonction qui appelle cette fonction, et argIdx est la position du paramètre dans la liste des paramètres. Ils sont utilisés pour générer le message d'erreur.

libraryUtil.checkTypeMulti

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

Génère une erreur si type( arg ) ne reconnait aucune des chaines dans le tableau expectTypes.

Cela sert pour les arguments qui ont plus d'un type valide.

libraryUtil.checkTypeForIndex

libraryUtil.checkTypeForIndex( index, value, expectType )

Génère une erreur si type( value ) ne correspond pas à expectType.

Ceci sert à implémenter une méta-méthode __newindex.

libraryUtil.checkTypeForNamedArg

libraryUtil.checkTypeForNamedArg( name, argName, arg, expectType, nilOk )

Génère une erreur si type( arg ) ne correspond pas à expectType. De plus, aucune erreur n'est générée si arg vaut nil et que nilOk vaut true.

Cette fonction est un équivalent de la fonction libraryUtil.checkType() pour les méthodes appelées en utilisant la syntaxe des paramètres nommés (func{ name = value }).

libraryUtil.makeCheckSelfFunction

libraryUtil.makeCheckSelfFunction( libraryName, varName, selfObj, selfObjDesc )

Cette fonction sert à implémenter des « méthodes » sur des tables destinées à être appelées avec la syntaxe obj:method(). Elle retourne une fonction qui peut être appelée au début de ces méthodes avec le paramètre self et le nom de la méthode, et génère une erreur si l'objet self n'est pas selfObj.

Cette fonction est en général utilisé dans les constructeurs de fonctions de bibliothèques :

 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

Les modules "bit" et "hex" de la bibliothèque luabit peuvent être chargés avec :

 bit = require( 'luabit.bit' )
 hex = require( 'luabit.hex' )

Notez que la bibliothèque bit32 contient les même opération que "luabit.bit", et les opération de "luabit.hex" peuvent être réalisées en utilisant les fonctions string.format() et tonumber().

Le module luabit "noki" n'est pas disponible, car il est inutile dans Scribunto.

Le module luabit "utf8 n'est pas non plus disponible, car il est considéré comme redondant avec la bibliothèque ustring

strict

La bibliothèque strict n'est pas une bibliothèque normale ; elle déclenche une erreur à chaque fois qu'une variable est utilisée sans avoir été explicitement définie comme variable locale (références à l'assignation des variables globales). Cette fonctionnalité est typiquement activée en chargeant en tête du module :

 require( 'strict' )

Sur de nombreux wikis Wikimedia, cela était auparavant implémenté dans Module:No globals, qui a été remplacé par phab:T209310. Il est en partie dérivé de strict.lua.

ustring

La bibliothèque Ustring du serveur, programmée uniquement en Lua, peut être chargée avec :

 ustring = require( 'ustring' )

Dans tous les cas la bibliothèque mw.ustring devrait être préférée car de nombreuses opérations lentes et gourmandes en mémoire sont remplacées par des appels à des fonctions PHP plus rapides.

Bibliothèques des extensions

Certaines extensions MediaWiki fournissent des bibliothèques Scribunto additionnelles. Elles sont aussi intégrées dans la table mw, généralement dans la table mw.ext, mais elles ne sont présentes que si certaines extensions sont installées, en plus de l’extension Scribunto elle-même.

Ces extensions utilisent les crochets fournis par Scribunto :

• ScribuntoExternalLibraries,
• ScribuntoExternalLibraryPaths.

La section Écrire des bibliothèques Scribunto décrit comment ces bibliothèques peuvent être développées pour fournir des interfaces Lua pour les extensions MediaWiki.

mw.wikibase

Client Wikibase donne accès à des données structurées localisables, notamment Wikidata. Voir docs_topics_lua.html et Extension:Client Wikibase/Lua .

mw.wikibase.lexeme

WikibaseLexeme donne accès aux entités Lexeme de Wikibase Ceci est pris en charge par Wikidata:Données lexicographiques. See md_docs_2topics_2lua.html and Extension:WikibaseLexeme/Lua .

mw.wikibase.mediainfo

WikibaseMediaInfo fournit l'accès aux entités Wikibase MediaInfo. Voir WikibaseMediaInfo/Lua . Ceci est pris en charge par Données structurées sur Commons. Voir Données structurées/Lua.

mw.bcmath

BCmath fournit une arithmétique de précision arbitraire aux modules Lua. Voir BCmath documentation via le lien « LDoc » à BCmath § Utilisation.

mw.smw

Semantic Scribunto fournit une prise en charge native Scribunto pour l’extension Semantic MediaWiki .

mw.ext.data

JsonConfig permet d’accéder à des données tabulaires et cartographiques localisables. Voir JsonConfig/Tabular . Tabular Data et GeoJSON Données cartographiques sont pris en charge dans l’espace de noms « Data: » à Commons.

• mw.ext.data.get( pagename )

mw.ext.cargo

Cargo fournit un moyen d'accéder à ses donnèes depuis Lua. Voir $see. Voir la prise en charge de Lua dans l’extension Cargo .

mw.ext.cattools

CategoryToolbox fournit un moyen de vérifier à partir de Lua si une page donnée appartient à une catégorie. Ceci est expérimental et non activé les wikis Wikimedia publics.

mw.ext.FlaggedRevs

FlaggedRevs fournit un moyen d'accéder aux paramètres de stabilité d'une page à partir de Lua.

mw.ext.TitleBlacklist

TitleBlacklist fournit un moyen de tester et d'obtenir des informations à propos des entrées nommées des pages en liste noire à partir de Lua.

mw.ext.ParserFunctions

ParserFunctions fournit un moyen à partir de Lua d’évaluer les expressions de la même manière que sa fonction d’analyse syntaxique basée sur PHP #expr .

mw.ext.proofreadPage

Proofread Page fournit l'accès aux espaces de noms Index et Page. Voir Extension:Proofread Page/Lua reference . Ceci est pris en charge par ProofreadPage. Voir Aide:Extension:ProofreadPage .

mw.ext.articlePlaceholder

ArticlePlaceholder fournit un moyen pour réécraser les rendus Wikibase par défaut à partir de Lua. Voir Extension:ArticlePlaceholder/Module:AboutTopic .

mw.ext.externalData

ExternalData fournit un moyen d'obtenir des données structurées d'Internet à partir de Lua. Voir Extension:External Data/Lua .

mw.ext.UnlinkedWikibase

Voir UnlinkedWikibase

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

mw.ext.seo

WikiSEO fournit un moyen de définir des données SEO pour la page en cours. Voir Extension:WikiSEO#Usage in lua modules.

mw.slots

WSSlots fournit un nombre de fonctions Lua pour travailler avec les positions MCR (Multi-Content Revisions) :

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

Différences avec le standard Lua

Fonctions changées

Les fonctions suivantes ont été modifiées :

setfenv()

getfenv()

Peut ne pas être disponible selon la configuration. Si disponible, tenter d'accéder à l'environnement parent échoue.

getmetatable()

Fonctionne sur les tables uniquement, afin d'empêcher l'accès à l'environnement parent.

tostring()

Les adresses des tables et fonctions ne sont pas accessibles, pour limiter l'exploitation d'éventuelles vulnérabilités.

pairs()

ipairs()

Support des méta-méthodes __pairs et __ipairs (ajoutés en Lua 5.2).

pcall()

xpcall()

Certaines erreurs internes ne peuvent pas être interceptées.

require()

Peut gérer certains modules inclus par défaut dans Scribunto ainsi que les modules présents dans l'espace de noms "Module:". Pour accéder aux modules wiki, utiliser le nom de complet de la page, avec l'espace de nom. Ne peut accéder au système de fichier local.

Fonctions et paquetages supprimés

Les paquetages suivants ont été supprimés ou presque. Seules les fonctions listées sont disponibles :

package.*

La gestion des systèmes de fichiers et la bibliothèque C sont supprimées. Les fonctions et tables disponibles sont :

package.loaded

package.preload

package.loaders

Les chargeurs qui accèdent au système de fichier local ou qui chargent des bibliothèque C sont absents. Un chargeur pour les modules dans l'espace "Module:" est ajouté.

package.seeall()

os.*

Certaines de ces fonctions sont non sécurisées (comme os.execute()). Les seules disponibles sont :

os.clock()

os.date()

os.difftime()

os.time()

debug.*

La plupart de ces fonctions sont non sécurisées. Les fonctions disponibles sont :

debug.traceback()

Les fonctions et paquetages suivants ne sont pas disponibles :

collectgarbage()

module()

coroutine.*

Aucun intérêt à être utilisé en Scribunto.

dofile()

loadfile()

io.*, file.*

Permet des accès au système de fichier local, ce qui n'est pas sécurisé.

load()

loadstring()

Enlevé pour permettre une analyse statique du code source Lua. De plus, ceci permettrait d'inclure du code Lua directement dans les articles et les modèles, ce qui n'est pas désiré.

print()

Ceci a été discuté sur wikitech-l et il a été décidé de préférer le retour de valeurs pour améliorer la qualité du code. Si nécessaire, mw.log() peut être utilisé dans la console de débogage.

string.dump()

Peut exposer des données privées de l'environnement parent.

Avertissements supplémentaires

Structures de données référentielles

Les structures de données circulaires et les structures de données où le même nœud peut être atteint par plus d'une voie ne peuvent pas être correctement envoyées à PHP. Tenter de le faire entrainera un comportement indéterminé. Cela inclut (mais n'est pas limité à) la restitution de ces structures de données à partir du module appelé par {{#invoke:}} et passer de telles structures de données en tant que paramètres aux fonctions des bibliothèques Scribunto qui sont mises en œuvre comme des rappels (callbacks) en PHP.
En revanche, de telles structures de données peuvent être utilisées librement dans Lua, y compris comme valeur de retour de modules chargés avec mw.loadData().

Écrire des bibliothèques Scribunto

Cette information est utile aux développeurs qui écrivent de nouvelles bibliothèques Scribunto, soit pour inclusion dans Scribunto, soit pour fournir une interface à leurs extensions.

Une bibliothèque Scribunto comporte en général cinq parties :

• la partie PHP de la bibliothèque ;
• la partie Lua de la bibliothèque ;
• la partie PHP des tests ;
• la partie Lua des tests ;
• la documentation.

Les bibliothèques existantes sont un bon exemple de code.

Bibliothèques

La partie PHP de la bibliothèque est une classe qui doit étendre Scribunto_LuaLibraryBase. Voir la documentation de cette classe pour les détails d'implémentation. Dans l'extension Scribunto, ce fichier doit être placé dans engines/LuaCommon/NomDeLaLibrary.php, et la classé doit être mappée dans Scribunto_LuaEngine::$libraryClasses. Les autres extensions peuvent utiliser l'accroche ScribuntoExternalLibraries. Dans les deux cas, la clé doit correspondre au nom du module Lua (mw.nom pour les bibliothèques de Scribunto ou mw.ext.nom pour les bibliothèques des extensions).

La partie Lua de la bibliothèque définit la table contenant les fonctions qui peuvent être appelées depuis les modules Lua. Dans une extension Scribunto, le fichier devrait être placé dans engines/LuaCommon/lualib/mw.name.lua. Ce fichier ressemble en général à :

local object = {}
local php

function object.setupInterface( options )
    -- Retirer la fonction setup
    object.setupInterface = nil

    -- Copier le callback PHP dans une variable locale et retirer la variable globale
    php = mw_interface
    mw_interface = nil

    -- Ajouter les autres initialisations ici

    -- Installer dans la variable globale mw
    mw = mw or {}
    mw.ext = mw.ext or {}
    mw.ext.NAME = object

    -- Indiquer que la bibliothèque est chargée
    package.loaded['mw.ext.NAME'] = object
end

return object

Le module dans engines/LuaCommon/lualib/libraryUtil.lua (chargez-le avec local util = require 'libraryUtil') contient diverses fonctions utiles pour réaliser cela.

Prenez soin de lancer les test cases Scribunto avec votre bibliothèque chargée même si votre bibliothèque ne fournit aucun test cases. Les tests standards contiennent des tests pour des choses comme des bibliothèques ajoutant des variables globales indésirables. Si la bibliothèque est chargée avec PHP, les valeurs des fonctions Lua ne seront pas réinitialisées lors d'un nouvel appel à {{#invoke}}. Il faut faire en sorte que les modules ne puissent pas utiliser ceci pour transférer des informations entre différents appels à {{#invoke}}.

Tests

L’extension Scribunto inclut une classe de base pour les cas de test, Scribunto_LuaEngineTestBase, qui exécutera les tests sur les moteurs LuaSandbox et LuaStandalone . Les tests de la bibliothèque devraient étendre cette classe et ne devraient pas remplacer static function suite(). Dans l’extension Scribunto, le cas de test doit être dans tests/engines/LuaCommon/NameLibraryTest.php et ajouté au tableau dans ScribuntoHooks::unitTestsList() (dans common/Hooks.php) ; Les extensions doivent ajouter le cas de test dans leur propre fonction d’accroche UnitTestsList , probablement sous réserve que $wgAutoloadClasses['Scribunto_LuaEngineTestBase'] soit défini ou non.

La plupart du temps, tout ce qui est nécessaire pour faire un cas de test est :

class ClassNameTest extends Scribunto_LuaEngineTestBase {
    protected static $moduleName = 'ClassNameTest';

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

Ceci va charger le fichier ClassNameTests.lua comme si c'était une page « Module:ClassNameTests », avec pour objectif de recevoir un objet avec les propriétés suivantes :

• count : entier, nombre de tests ;
• provide( n ) : fonction qui retourne trois valeurs : n, le nom du test n, et une chaine qui est la sortie attendue du test n ;
• run( n ) : fonction qui exécute le test n et retourne une chaine.

Si getTestModules() est déclaré visible, "Module:TestFramework" est disponible et fournit de nombreuses fonctions d'aide. Si utilisé, ClassNameTests.lua ressemblerait à quelque chose comme :

local testframework = require 'Module:TestFramework'

return testframework.getTestProvider( {
    -- Les tests sont ici
} )

Chaque test est lui-même une table avec les propriétés suivantes :

• name : le nom du test ;
• func : la fonction à exécuter ;
• args : une table optionnelle de paramètres à passer à la fonction ;
• expect : le résultat attendu ;
• type : le type (optionnel) du test ("Normal" par défaut).

Le type contrôle le format de expect et comment func est appelée. Les types sont :

• Normal : expect est une table des valeurs retournées, ou une chaine si le test devrait générer une erreur. func est simplement appelée ;
• Iterator : expect est une table de tables de valeurs retournées. func est appelée comme avec un itérateur de boucle, et chaque retour d'itération est cumulé.
• ToString : comme "Normal" mis à part que chaque valeur retournée est passée à tostring().

Tests dans une autre extension

Il existe au moins deux façons d'effectuer des tests PHPUnit :

1. Exécuter phpunit sur core afin de permettre à tests/phpunit/suites/ExtensionsTestSuite.php de trouver les tests des extensions en utilisant UnitTestsList . Si tous les noms de classe de vos tests d'extension contiennent un terme unique commun (par exemple le nom de l'extension), il est possible d'utiliser l'option --filter pour n'exécuter que vos tests d'extension ;
2. Exécuter phpunit sur le répertoire d'extensions, dans lequel il sélectionnera tout fichier se terminant par "Test.php".

Ces deux approches fonctionneront correctement si Scribunto est chargé dans LocalSettings.php. Et il est facile d'utiliser la première méthode si Scribunto n'est pas chargé car le hook UnitTestsList peut être écrit afin d'éviter de retourner le test Scribunto quand $wgAutoloadClasses[ 'Scribunto_LuaEngineTestBase' ] n'est pas défini.

Mais Jenkins utilise la deuxième méthode. Pour que Jenkins exécute correctement les tests, vous devrez ajouter Scribunto comme une dépendance pour votre extension. Voir Gerrit change 56570 pour un exemple.

Si vous avez besoin de lancer les tests en utilisant la deuxième méthode sans que Scribunto ne soit chargé, il est possible de le faire en ajoutant cette vérification au début de vos fichiers de tests :

 if ( !isset( $GLOBALS['wgAutoloadClasses']['Scribunto_LuaEngineTestBase'] ) ) {
     return;
 }

Documentation

Les modules pour Scribunto doivent inclure une documentation dans la section Bibliothèques Scribunto (plus haut). Les bibliothèques d'extension doivent inclure une documentation dans une sous-page de leur propre page d'extension, et insérer un lien vers cette documentation dans la sous-section bibliothèques des extensions (plus haut).

Voir aussi

• Lua (langage de programmation)

Licence

Ce manuel est dérivé du Manuel de référence de Lua 5.1, qui est disponible sous la licence MIT.

Ce manuel modifié peut également être copié, en respectant les conditions de la même licence.