Extension:Scribunto/Lua reference manual/fr

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



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

Sauvegardez puis, dans une autre page (qui ne soit pas un module), écrivez :

Vous pouvez remplacer « Banane » par le nom de module de votre choix. Ceci va appeler la fonction « hello » exportée par ce module. Le code sera remplacé par le texte que cette fonction retourne, dans cet exemple « Hello, world! ».

C'est généralement une bonne idée d'invoquer un code Lua depuis un modèle plutôt que directement dans les pages. De cette façon, la syntaxe est constante que le code ait été écrit en lua ou en wikicode. Cela évite aussi d'introduire une nouvelle syntaxe complexe dans les pages de l'espace de noms principal d'un wiki.

Structure d'un module
Le module lui-même doit retourner une table contenant des fonctions qui peuvent être appelée via la syntaxe. 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 à cette table, et la table est retournée à la fin du module.

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

Transmission des paramètres depuis le wikitexte

Les fonctions appelées par  reçoivent un seul paramètre, un objet frame. Les paramètres transmis par  sont dans la table   de l'objet frame. Il est aussi possible d'accéder aux paramètres transmis au modèle contenant  en utilisant la fonction  frame:getParent  pour accéder à la table   de ce frame là.

L'objet frame peut aussi être utilisé pour utiliser des fonctions parseurs, des modèles, ou pour traiter une chaine de wikitexte.

Retourner du texte
La fonction du module doit normalement retourner une chaine. Quelles que soient les valeurs retourné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 en replacement du.

À ce moment du traitement de la page, les modèles ont déjà été évalués, les fonctions du parseur, les tags ont déjà été traités, et les transformations de pré-sauvegarde déjà effectuées (comme la signature avec Zebulon84 (talk) 02:01, 10 July 2017 (UTC)). Ainsi un module ne peut pas utiliser ces fonctionnalités dans sa sortie. Par exemple si un module retourne, la page contiendra "Hello, world!  ".

D'autre part, subst est géré plus tôt dans le traitement d'une page, donc avec  seules les substitutions ultérieures ne seront pas évaluées. Comme les substitutions vont rester dans le wikitexte elle ne seront traitées que lors de la prochaine sauvegarde. Cette situation devrait être évitée autant que possible.

Documentation d'un module
Scribunto permet la documentation d'un module en utilisant une sous-page particulière du module lui-même. Par défaut il s'agit de la sous-page "/doc", et son contenu est inclus en début de module lors de la visualisation. La sous-page de documentation est au format wikitexte (et non Lua bien que dans l'espace Module:). Par exemple la documentation du module "Module:Banane" sera dans la sous-page "Module:Banane/doc".

Ceci peut se configurer en utilisant les messages systèmes (les messages de l'espace MediaWiki) :


 * scribunto-doc-page-name : fixe le nom de la sous-page de documentation. Le nom du module (sans le préfixe « Module: ») est transmis dans la variable . Si cette sous-page est dans l'espace module elle est traitée comme étant du wikitexte et non du code Lua (et ne doit donc pas être invoquée avec  ). Sa valeur par défaut est "Module:$1/doc", c'est-à-dire la sous-page /doc du module. Les fonctions parseurs  et autre fonctions entre accolade de devraient pas être utilisées dans ce message.
 * scribunto-doc-page-does-not-exist : message affiché lorsque la sous-page de documentation n'existe pas. Le nom de la sous-page est . Sa valeur par défaut un message vide.
 * scribunto-doc-page-show : message affiché lorsque la sous-page de documentation existe. Le nom de la sous-pages est . Le comportement par défaut est la transclusion de la documentation.
 * scribunto-doc-page-header : entête affiché quand on lit la sous-page de documentation elle-même. Le nom du module dont c'est la page de documentation est  ; la valeur par défaut est une courte explication en italique.

Notez que les modules ne peuvent être directement catégorisés ni avoir de liens interwikis par ces messages. Ceci peut se faire dans la documentation à l'intérieur d'une partie, qui ne sera ainsi appliquée qu'au module et non à la sous-page de documentation elle-même.

Entités
Les Noms (aussi appelés identifiants) dans Lua peuvent être formés de n'importe quelle séquence ASCII de lettres (de  à   ou de   à  ), chiffres (de   à  ) et tirets bas  à l'exception du premier caractère qui ne peut pas être 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 :



Par convention, les mots-clés commençant par un tiret bas et suivis de lettres capitales sont réservés comme variables globales internes à Lua (exemple : _VERSION).

Les séquences de caractères suivantes correspondent à d'autres mots-clés de Lua :



Commentaires
Un commentaire commence par  n'importe où en dehors d'une chaine. 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é.

Types et valeurs
Lua est un langage typé dynamiquement. Cela signifie que les variables n'ont pas de type, seules les valeurs en ont. Il n'y a aucune définition de type dans ce langage, chaque valeur transportant son propre type.

Lua possède huit types basiques, toutefois seuls six sont utilisables en Scribunto. La fonction  retourne le type de toute valeur (sous forme de chaine).

La fonction  convertit une valeur en chaine. La fonction  convertit une valeur en nombre si possible, et retourne nil sinon. Il n'existe aucune fonction pour convertir explicitement une valeur dans un autre type que ceux-ci.

Les nombres sont automatiquement convertis en chaines quand ils sont utilisés là où une chaine est attendue (par exemple avec l'opérateur de concaténation). Les chaines reconnues par  sont automatiquement converties en nombres quand elles sont utilisées avec des opérateurs arithmétiques. Quand un booléen est attendu toute valeur autre que nil et false est vraie.

nil
« Nil » est le type de donnée pour, qui existe pour représenter l'absence de valeur.

« Nil » ne doit pas être utilisé comme clé dans une table et il n'y a pas de différence entre un élément sans valeur (jamais assigné) et un élément avec la valeur nil.

Sa conversion en chaine est "nil", et sa conversion en booléen est false.

Booléen
Les valeurs possibles d'un booléen sont  et.

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

Contrairement à d'autres langages, les booléens ne peuvent être convertis directement en nombres. Toujours contrairement à d'autres langages seuls false et nil sont faux, le nombre 0 et la chaine vide étant tout deux considérés comme true.

Chaine
Les chaines en Lua sont considérées comme une série d'octets (8 bits), et c'est à l'application de les interpréter dans un encodage particulier.

Les chaines constantes peuvent être délimitées par des guillemets ou des apostrophes ( ou  ). Comme en JavaScript et contrairement à PHP il n'y a aucune différence entre ces deux notations. Les séquences d'échappement suivantes sont reconnues en Lua :


 * (bell, caractère d'appel, 7)
 * (backspace, espacement arrière, 8)
 * (horizontal tab, tabulation horizontale, 9)
 * (newline, saut de ligne, 10)
 * (vertical tab, tabulation verticale, 11)
 * (form feed, saut de page, 12)
 * (carriage return, retour à la ligne, 13)
 * (double quote, guillemets droits, 34)
 * (single quote, apostrophe droite, 39)
 * (backslash, barre oblique inversée, 92)

Un vrai retour à la ligne peut aussi être inclus en le précédant d'un backslash ("\"). Les octets peuvent aussi être donnés en utilisant la séquence d'échappement '\ddd', avec ddd une valeur décimale entre 0 et 255.

Pour inclure un caractère Unicode avec des séquences d'échappement, chaque octet doit être spécifié en suivant les valeurs du caractère (voir UTF-8). Il est nettement plus simple en général de taper directement le caractère Unicode désiré (le lua de Scribunto transforme les chaines littérales en leur représentation UTF-8, ce qui n'est pas standard en lua).

Une chaine constante peut aussi être définie en utilisant des crochets longs. Un crochet long ouvrant est un crochet ouvrant suivi éventuellement d'un ou plusieurs signes « égal » ("=") et terminé d'un autre crochet ouvrant. Exemples :,  , ou. Un crochet long ouvrant doit correspondre à un crochet long fermant (ayant le même nombre de signes « égal »). Exemples :,  , ou. Les chaines délimitées par des crochets longs ne sont pas interprétées, ce qui veut dire que les séquences d'échappement sont traitées comme du texte normal. Le seul cas particulier est la présence d'un retour à la ligne juste après le crochet long ouvrant, auquel cas ce retour à la ligne n'est pas intégré à la chaine. Chaque saut de ligne, quel que soit son codage, est interprété comme un seul caractère '\n' (newline, saut de ligne).

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

Nombre
Lua n'a qu'un seul type de nombre représenté en interne par des nombres à virgule flottante double précision. Dans ce format les entiers entre -9007199254740992 et 9007199254740992 peuvent être représentés exactement, et les entiers plus petits ou plus grands auront des erreurs d'arrondi.

Les nombres non entiers sont notés avec le point comme séparateur décimal et sans séparateur de groupe (exemple :  ). Les nombres peuvent aussi utiliser la notation en exposant sans espace (exemples :,  , ou  ). Les entiers peuvent aussi être donnés en notation hexadécimale en utilisant le préfix  (exemple :  ).

Bien que Lua gère l'infini positif et négatif ainsi que NaN il n'y a pas de constante permettant de les représenter. La constante  représente l'infini positif de même que la division par zéro , et   permet de représenter efficacement NaN.

Notez que tous les nombres sont considérés comme vrais en cas de conversion en booléen, alors que dans de nombreux autres langages 0 est considéré comme faux. Lors d'une conversion en chaine, les nombres finis sont représentés sous forme décimale, éventuellement en notation avec exposant. NaN devient "nan" ou "-nan" et les infinis deviennent "inf" ou "-inf".

Table
Les tables en 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 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 plusieurs formes :


 * utilise la (première) valeur de expression1 comme la clé et la (première) valeur de expression2 comme valeur ;
 * est équivalent à  ;
 * est à peu près équivalent à, où i 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 retournant plusieurs valeurs, toutes ces valeurs sont utilisées ; dans tous les autres cas seule la première valeur retournée l'est.

On accède aux éléments d'une table en utilisant des crochets, comme avec. Lorsque la clé est une chaine simple (lettres sans accent et chiffres), on peut aussi y accéder en utilisant le point, par exemple en écrivant. Cela est équivalent à. Pour appeler une fonction contenue dans une table, on peut utiliser le deux-points, par exemple :. Cette notation est équivalente à.

Une séquence est une table avec des valeurs définies (autres que nil) pour tous les entiers de 1 à N et des valeurs non définies pour tous les entiers supérieurs à N. De nombreuses fonctions Lua ne fonctionnent que sur des séquences (ignorant les clés négatives ou celles placées après une valeur nil).

Contrairement à PHP ou JavaScript toute valeur en dehors de nil et de Nan peuvent être utilisées comme clé et aucune conversion n'est effectuée. Les entrées ci-dessous sont toutes valides et distinctes :

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çue 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 chaine, le résultat est "table". Ceci peut être modifié en changeant la méta-méthode. Même la table vide est considérée comme true en tant que booléen.

Fonction
En Lua les fonctions sont des objet de première classe : elles peuvent être créées anonymement, être passées en paramètre, assignées à des variables…

Les fonctions sont créées grâce au mot-clé  et appelées en utilisant les parenthèses. 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 transmis en paramètre à une autre fonction.

La conversion en chaine d'une fonction retourne "function".

Types non supportés
Le type userdata permet de stocker des données opaques pour les extensions pour 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.

Le type thread permet de gérer les co-routines, qui ne sont pas disponibles en Scribunto.

Méta-tables
Chaque table peut avoir une table associée appelée méta-table. Les champs dans 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 elles sont accédées pour leurs méta-fonctions, les méta-tables sont accédées avec rawget.

Les champs d'une méta-table qui impactent la table elle-même sont :
 * __index
 * utilisé quand l'accès  aurait retourné nil. Si la valeur de ce champ est une table, l'accès sera tenté de nouveau dans cette table (par exemple , ce qui pourra a son appelé la méta-table de cette table). Si la valeur de ce champ est une fonction, celle-ci est appelée ainsi :  .  La fonction rawget court-circuite cette méta-méthode.


 * __newindex
 * utilisé lorsqu'une valeur est assignée à une clé de la table et qu'il n'y a pas de valeur pour cette clé ( avec   qui aurait retourné nil). Si la valeur de ce champ est une table l'affectation sera répétée dans cette table . Si la valeur de ce champ est une fonction celle-ci est appelée comme suit :  . La fonction rawset court-circuite cette méta-méthode.


 * __call
 * utilisé quand la syntaxe d'un appel de fonction est utilisé sur une table, . Cette valeur doit être une fonction, qui est appelée comme suit :.


 * __mode
 * utilisé pour que les tables puissent contenir des références faibles (weak references). Cette valeur doit être une chaine. Par défaut toute valeur utilisée comme clé ou valeur dans une table ne sera pas nettoyée par le nettoyeur de mémoire (garbage collector). Mais si ce méta-champ contient la lettre « k » les clés peuvent être « nettoyées », et si il contient la lettre « v » les valeurs peuvent être « nettoyées ». Dans les deux cas la paire clé-valeur correspondante sera effacée de la table si l'un des éléments est « nettoyé ». Notez que le comportement est non défini en cas de modification de ce champ dans une 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, ne sont pas considérées comme identiques. * __metatable affecte getmetatable et setmetatable.

Note : en lua, toutes les chaines 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. De même string n'est pas disponible, seule une copie 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 globales à moins d'être explicitement déclarées comme locales, en utilisant le mot-clé. Toute variable à laquelle on n'a pas affecté de valeur contient la valeur nil.

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

L'environnement d'une fonction peut être accédé en utilisant la fonction 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 Déclaration de variables locales.

Expressions
Une expression sert à évaluer et éventuellement retourner une ou plusieurs valeurs : 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, les expressions vararg, 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 ne retourne qu'une seule valeur. Les appels de fonctions et les expressions vararg peuvent en retourner un nombre quelconque (y compris aucune). Notez que l'encadrement entre parenthèses d'un appel de fonction ou d'une expression vararg lui fait perdre toutes les valeurs sauf la première (si l'appel de fonction ou l'expression vararg ne retourne aucune valeur, la valeur nil sera utilisée).

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 retourné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 convertibles en nombre par tonumber, les opérations ont leur fonctionnement habituel.

Si l'un des opérandes est une tables avec une méta-méthode appropriée, cette méta-méthode sera utilisée. Sinon le résultat de l'opération sera nil si l'un des opérandes converti en nombre retourne nil, puis Nan si un des opérandes (après sa conversion en nombre) a une valeur NaN.

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 à exactement le même objet ( 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.

La différence (ou inégalité) est l'exacte négation 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 :


 * utilise  (si a et b sont des tables, leur méta-méthode   doit référencer la même fonction, sinon elle ne sera pas utilisée).
 * utilise  si disponible, ou si   est disponible alors   est utilisé (qui ne retournera que false ou true et donc permet de définir une relation d'ordre total).
 * est considéré comme équivalent à b < a et utilise __lt( b, a ).
 * a >= b est considéré comme équivalent à b <= a et utilise __le( b, a ) si disponible, sinon not _lt( a, b ) (qui ne retournera que false ou true et donc permet de définir une relation d'ordre total).

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,  , et. Tous considèrent nil et false comme faux et toutes les autres valeurs comme vraies.

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

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

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

Notez que  et   n'évaluent pas systématiquement leur opérande de droite. Par exemple foo or bar appelera bar uniquement si foo retourne false ou nil comme première valeur.

Opérateur de concaténation
L'opérateur de concaténation est constitué de deux points. Si les deux opérandes sont des nombres ou des chaines, ils sont convertis en chaines et concaténées. Sinon, si une méta-méthode  est disponible, elle est utilisée. Sinon 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  aura à créer une nouvelle chaine à chaque itération et éventuellement le nettoyage mémoire s'occupera des chaines plus utilisé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 sequence et d'utiliser table.concat ensuite.

Opérateur de longueur
L'opérateur de longueur est, utilisé comment suit :. Si  est une chaine il retourne la longueur en octets. Si a est une table séquence il retourne la longueur de la séquence.

Si  est une table qui n'est pas une séquence,   peut retourner n'importe quelle valeur N telle que   est différent de nil et   vaut nil, même si il y a d'autres valeurs non-nil à des index plus élevés. Par exemple :

Préséance des opérateurs
Voici la préséance des opérateurs, de la plus haute priorité à la plus basse :


 * 1) not # - (négation numérique)
 * 2) + - (soustraction)
 * 3) and
 * or
 * 1) and
 * or
 * 1) and
 * or

La plupart des opérateurs ayant la même préséance sont associatifs à gauche. Par exemple,  est interprété comme.

L'exposant et la concaténation sont en revanche associatifs à droite. Par exemple,  est interprété comme , et   est interprété  comme.

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.

func( liste-d'expressions )

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

Si une fonction est appelée avec moins de valeurs dans la liste d'expression que le nombre de paramètres définis dans la fonction, les paramètres additionnels auront la valeur nil. Si la liste d'expression 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. 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:name( liste-d'expressions )

est strictement équivalente à :

table.name( table, expression-list )

Le second cas est la façon dont Lua met en œuvre les paramètres nommés, en passant comme seul paramètre une table contenant une liste de nom-valeur. Dans ce cas, les parenthèses autour de la liste de paramètres sont optionnelles. Ceci fonctionne aussi si la fonction ne reçoit qu'une chaine 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 ( var-list ) block end

Toutes les variables dans var-list 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 block.

Quand la fonction est appelée, les déclarations de block sont exécutées après la création et l'affectation des variables locales correspondant à var-list. Si un return est rencontré le bloc se termine et les valeurs de l'expression correspondant à l'appel de la fonction sont celles passées au 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 :

Une fonction peut être déclarée pour accepter un nombre variable de paramètres en indiquant  comme élément final dans var-list :

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

À l'intérieur du bloc de la fonction, l'expression vararg (pour variable arguments, « paramètres variables »)  peut être utilisée. Elle vaut l'ensemble des valeurs passées en paramètres additionnels lors de l'appel à la fonction. Par exemple :

La fonction select sert à traiter les expressions vararg. En particulier  doit être utilisée au lieu de   pour compter le nombre de valeurs dans l'expression vararg car   n'est pas forcément une table séquence.

Lua fournit un raccourci syntaxique pour combiner la déclaration et l'assignement à 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, "factorial" 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 tâche, un élément de contrôle, un appel de fonction, une déclaration de variable…

Un morceau (chunk, terme anglais utilisé par la suite plutôt que la traduction qui « perd » un peu de son sens) est une séquence d'instructions, éventuellement séparées par des point-virgules. Un chunk est considéré comme le corps d'une fonction anonyme, donc il peut déclarer des variables locales, recevoir des paramètres et retourner 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 :. Ceci peut être utilisé pour limiter la portée de variables locales ou pour ajouter un  ou un   au milieu d'un autre bloc.

Affectations
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 affectation ne soit effectuée, donc  va effectivement échanger les valeurs contenues dans a et b.

Déclaration locale de variables
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 Affectations.

Notez que la visibilité d’une variable locale commence à l’endroit où elle est déclarée. Donc une déclaration telle que  déclare une variable x et lui affecte la valeur de x dans la portée au dessus. Une variable locale reste visible jusqu’à la fin du bloc où elle a été déclarée.

Structures de contrôle
L'instruction while répète le bloc block tant que l'expression exp est vraie.

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

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 exp1 à exp2 en ajoutant exp3 à chaque itération. Notez que exp3 peut être omise auquel cas la valeur 1 est utilisée ; cependant des valeurs non numériques comme nil et false sont incorrectes. Toutes les expressions 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 bloc. 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.

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

Cette forme 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 première variable de var-list if var == nil then break end block end end

mis à part une fois encore que les variables func, static et var ne sont pas accessibles. Notez que les variables var-list 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, exp-list est une unique fonction qui retourne 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 suggère d'utiliser une fermeture plutôt que de retourner une table en tant que variable statique et de mettre à jour ses membres à chaque itération.

Exécute block1 si exp1 retourne vrai, sinon exécute block2 si exp2 retourne vrai, et block3 sinon. La partie  peut être omise, et la partie   peut être omise ou répétée autant que nécessaire.

L'instruction return est utilisée pour retourner une valeur dans une fonction ou un chunk (qui est une fonction). expression-list 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 expression-list 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  ou.

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 ) peut être utilisé.

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 ) peut être utilisé.

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'affecter à une variable. Les paires de déclarations suivantes sont équivalentes :

-- déclarations "basiques" function func( var-list ) block end func = function ( var-list ) block end

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

-- fonction comme champ d'une table function table.func( var-list ) block end table.func = function ( var-list ) block end

-- fonction comme méthode d'une table function table:func( var-list ) block end table.func = function ( self, var-list ) block 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 explicitement un paramètre "self" au début de la liste des paramètres.

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 » 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 chaines…

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.

_G


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

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

_VERSION


Une chaine qui contient la version courante de Lua (exemple : "Lua 5.1").

assert
Si  est nil ou false, la fonction génère une erreur. Dans ce cas,  est utilisé comme texte du message d'erreur. Si message est nil ou non indiqué, le texte de l'erreur sera « assertion failed! ». Si message est une chaine ou un nombre, son contenu est utilisé, autrement assert lui-même génère une erreur.

Si  a toute autre valeur, assert retourne tous les paramètres y compris   et.

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  comme suit :

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

ajoute normalement des informations à l'endroit où l'erreur s'est produite. Si  est 1 ou n'est pas précisé, cette information est à l'endroit où se trouve l'appel à , 2 indique l'endroit où s'est fait l'appel à la fonction qui a appelé   et ainsi de suite. Passer 0 désactive l'affichage de cette information.

getfenv
Notez que cette fonction peut ne pas être disponible selon la configuration du système.

Retourne un environnement (une table globale) comme indiqué par  :


 * si 1, nil ou absent, retourne l'environnement de la fonction qui appelle . La plupart du temps ceci a le même effet que _G.
 * 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 la pile correspondante est une récursion terminale.
 * Passer une fonction retourne l'environnement qui sera utilisé par 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  retournera nil systématiquement.

getmetatable
Retourne 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, cette valeur sera retournée au lieu de la vraie méta-table.

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

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

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

Le comportement standard peut être évité en fournissant une méta-méthode. Si cette méta-méthode existe, l'appel à ipairs retournera les trois valeurs retournées par  à la place.

next
Permet d'itérer sur les clés d'une table. Si  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.

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
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  :

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. Si cette méta-méthode existe l'appel à pairs retournera les trois valeurs retournées par  à la place.

pcall
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 retournera false suivi du message d'erreur correspondant. Si aucune erreur ne se produit pcall retournera true suivi de toutes les valeurs retournées par l'appel.

La fonction pcall pourrait ressembler à quelque chose comme suit :

rawequal
Ceci est équivalent à  mis à part qu'une éventuelle méta-méthode   sera ignorée.

rawget
Ceci est équivalent à  mis à part qu'une éventuelle méta-méthode   sera ignorée.

rawset
Ceci est équivalent à  mis à part qu'une éventuelle méta-méthode   sera ignorée.

select
Si index est un nombre, retourne tous les paramètres de  après cet index. Si index est la chaine '#', retourne le nombre total de paramètres dans

En d'autres mots select est globalement équivalent au code suivant mis à part qu'il fonctionne correctement même quand  contient des valeurs nil (voir la documentation de # et unpack pour les problèmes liés aux nil) :

setmetatable
Fixe la méta-table d'une table. metatable peut être nil mais doit être explicitement indiquée.

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

tonumber
Tente de convertir valeur en nombre. Si c'est un nombre ou une chaine convertible en nombre, alors tonumber retourne ce nombre ; sinon retourne 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 supérieurs à 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 exposant (comme ). Dans les autres bases, seuls les entiers sont acceptés.

Le préfixe "0x" sur la valeur indique la base 16 sans qu'il soit nécessaire de le spécifier.

tostring
Permet de convertir valeur en chaine. Voir Types et valeurs pour les détails sur comment chaque type est converti.

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

type
Retourne le type de valeur dans une chaine. Les résultats possibles sont : "nil", "number", "string", "boolean", "table", et "function".

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

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
Cette fonction est similaire à pcall mis à part que le message d'erreur est passé à la fonction errhandler avant d'être retournée.

La fonction xpcall pourrait ressembler à quelque chose comme suit :

debug.traceback
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.

math.abs
Retourne la valeur absolue de x.

math.acos
Retourne l'arc cosinus de x (en radians).

math.asin
Retourne l'arc sinus de x (en radians).

math.atan
Retourne l'arc tangente de x (en radians).

math.atan2
Retourne l'arc tangente de  (en radians), mais utilise le signe des deux paramètres pour trouver le quadrant du résultat. (Il gère aussi correctement le cas où x vaut zéro.)

math.ceil
Retourne le plus petit entier plus grand ou égal à x.

math.cos
Retourne le cosinus de x (exprimé en radians).

math.cosh
Retourne le cosinus hyperbolique de x.

math.deg
Retourne l'angle x (donné en radians) en degrés.

math.exp
Retourne la valeur $$e^x$$.

math.floor
Retourne le plus grand entier plus petit ou égal à x.

math.fmod
Retourne le reste de la division euclidienne de x par y.

math.frexp
Retourne m et e tels 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 est NaN ou infini : m est x et e est indéfini.

math.huge
La valeur qui représente l'infini positif, plus large ou égale à n'importe quelle valeur numérique.

math.ldexp
Retourne $$m \times 2^e$$ ( e doit être un entier).

math.log
Retourne le logarithme naturel de x.

math.log10
Retourne le logarithme en base 10 de x.

math.max
Retourne la valeur la plus grande parmi les paramètres reçus.

Le comportement avec NaN n'est pas spécifé. Dans l'implémentation actuelle, NaN sera retourné si la première valeur est NaN, mais les autres NaN seront ignorés.

math.min
Retourne la valeur la plus petite parmi les paramètres reçus.

Le comportement avec NaN n'est pas spécifé. Dans l'implémentation actuelle, NaN sera retourné si la première valeur est NaN, mais les autres NaN seront ignorés.

math.modf
Retourne deux nombres, la troncature à l'unité de x et la partie fractionnaire de x. Par exemple  retourne   et   retourne.

math.pi
La valeur de $$\pi$$.

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

math.rad
Retourne l'angle x (donné en degrés) en radians.

math.random
Retourne un nombre pseudo-aléatoire.

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


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

math.randomseed
Fixe x comme « graine » pour le générateur de nombres pseudo-aléatoires.

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

math.sin
Retourne le sinus de x (donné en radians).

math.sinh
Retourne le sinus hyperbolique de x.

math.sqrt
Retourne la racine carrée de x (vous pouvez également utiliser  pour calculer cette valeur).

math.tan
Retourne la tangente de x (donné en radians).

math.tanh
Retourne la tangente hyperbolique de x.

os.clock
Retourne une approximation du temps CPU consommé par le programme, en secondes.

os.date

 * La fonction formatDate de la bibliothèque Language peut être utilisée pour une mise en forme de dates plus claires.

Retourne une chaine 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,  est utilisé.

Si time est indiqué, il est utilisé comme heure à formater (voir ). 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, la date est retournée dans une table avec les champs suivants :


 * year (complet) ;
 * month (1–12) ;
 * day (1–31) ;
 * hour (0–23) ;
 * min (0–59) ;
 * sec (0–60) ;
 * wday (jour de la semaine, dimanche valant 1) ;
 * yday (jour de l'année) ;
 * isdst (drapeau de présence de l'heure d'été, un booléen. Peut être absent si l'information n'est pas disponible).

Si format n'est pas, 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
Retourne le nombre de secondes séparant t1 de t2.

os.time
Retourne 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.

require
Charge le module indiqué.

Tout d'abord, cette fonction regarde dans  pour voir si le module est déjà chargé. Si c'est le cas retourne.

Sinon appelle chaque chargeur (loader) dans  pour tenter de trouver un chargeur pour ce module. Si un chargeur est trouvé, alors il est appelé. La valeur retournée par ce chargeur est stockée dans  et est ensuite retournée.

Voir la documentation de  pour les chargeurs disponibles.

Notez que chaque module chargé par require est chargé dans son propre environnement. Il n'est donc pas possible d'exporter des variables globales depuis un module chargé vers le module courant comme c'est parfois fait en Lua 5.1. Au lieu de cela, tout ce que le module veut exporter doit être inclus dans la table que retourne celui-ci.

Par exemple, si vous avez un « Module:Exemple » écrit comme suit :

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

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) La recherche avec   pour la fonction de chargement ;
 * 2) La recherche avec les modules fournis par Scribunto pour le nom du module, et si cela échoue, la recherche dans l'espace de noms « Module: ». Dans ce dernier cas, le préfixe « Module: » doit être présent dans le nom du module.

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
Fixe la méta-méthode  pour table à.

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…

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

string.byte
Si la chaine est considérée comme une table d'octets, retourne les octets,. La valeur par défaut de i est 1, la valeur par défaut de j est i. Identique à mw.ustring.byte.

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.

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

string.find
Cherche la première correspondance de motif  dans la chaine s. Si une correspondance est trouvée, alors find retourne les indices de s où cette occurrence commence et se termine, sinon il retourne nil. Si le motif a des captures, alors si une correspondance est trouvée le résultat de des captures est également retourné 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 sansMotif 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 motif n'étant alors considéré comme ayant de sens particulier.

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

Voir mw.ustring.find pour une fonction similaire qui utilises les motifs Ustring et où le décalage init est en caractères plutôt qu'en octets.

string.format
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 chaine de format formatstring suit les mêmes règles que les fonctions de la famille en C standard.


 * les attributs reconnus sont '-', '+', ' ', '#', et '0' ;
 * les largeur minimale de champ sont supporté jusqu'à 99. '*' n'est pas supporté ;
 * les précision sont sont supporté jusqu'à 99. '*' n'est pas supporté ;
 * les modificateur de longueur ne sont pas supporté ;
 * les indicateur de conversion reconu 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é.

L'option de conversion q est similaire à s mais formate la chaine de façon à ce qu'elle soit sainement utilisable par l'interpréteur Lua : la chaine est écrite entre guillemets, et les guillemets, retours à la ligne, codes zéros et les barres obliques inversées  présents dans le paramètre formatstring sont échappées correctement.

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 ne sont pas correctement gérées.

Identique à mw.ustring.format.

string.gmatch
Retourne une fonction d'itération qui, chaque fois qu'elle est appelée, retourne les captures de la correspondance suivante de motif dans la chaine s. Si pattern ne spécifie pas de capture, alors la correspondance complète est retourné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.

voir mw.ustring.gmatch pour une fonction similaire pour laquelle les motifs sont décrits dans motifs Ustring.

string.gsub
Retourne une copie de s dans laquelle toutes (ou les n premières, si le paramètre est indiqué) occurrences de motif  ont été remplacées par la chaine de remplacement précisée dans rempl, qui peut être une chaine, une table ou une fonction. gsub retourne également comme deuxième valeur le nombre total de correspondances trouvées.

Si rempl 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 rempl de la forme , avec n un entier entre 1 et 9, signifie la valeur de la n-ième sous-chaine capturée (voir plus bas). La séquence  correspond à la correspondance complète. La séquence  correspond à un simple.

Si rempl 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 rempl 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
Reçoit une chaine et retourne sa longueur en octets. La chaine vide "" a une longueur de 0. Les zéros ("\0") sont cependant comptabilisés. Ainsi "a\000bc\000" a une longueur de 5. Équivalent à.

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

string.lower
Reçoit une chaine et retourne une copie de cette chaine avec tous les caractères ASCII majuscule changés en minuscule. Tous les autres caractères sont laissés tels quels (notamment les lettres accentuées comme  sont inchangée).

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
Cherche la première correspondance de motif  dans la chaine s. Si une correspondance est trouvée, match retourne les captures correspondantes, sinon il retourne nil. Si motif ne précise pas de capture, alors la correspondance complète est retourné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
Retourne une chaine qui est la concaténation de n copies de la chaine s. Identique à mw.ustring.rep.

string.reverse
Retourne une chaine qui est la chaine s renversée (début ↔ fin, octet par octet). Ne fonctionne pas avec des caractères Unicodes.

string.sub
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 est absent il est considéré comme valant -1 (qui signifie la longueur de la chaine).

En particulier  retourne un préfixe de s de longueur j, et   retourne un suffixe de longueur i de s.

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

string.upper
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.

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 chariot ;
 * 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 ;
 * Pas moyen de quantifier de manière précise (comme le ferait  avec PCRE) ;
 * Les seuls caractères de contrôle qui n’ont aucune profondeur sont,   et  , le motif de « frontière » (Lua n’offre pas la possibilité d’utiliser   ou   qui apparaissent dans les PCRE).
 * 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 », ). Utilisez  à 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 quelconque : 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 15 caractères « magiques »  ) représente le caractère x lui-même.
 *   : (le point de ponctuation) représente un caractère quelconque, y compris un saut de ligne, ou un caractère de contrôle ou un octet non ASCII.
 *   : représente les lettres ASCII (, sans les lettres accentuées).
 *   : représente les caractères de contrôle ASCII, y compris les tabulations et sauts de ligne.
 *   : représente les chiffres latins.
 *   : représente les lettres ASCII minuscules.
 *   : représente les signes de ponctuation et les symboles du jeu de caractères ASCII.
 *   : représente les caractères d’espacement ASCII (l’espace et les contrôles de tabulation ou de saut de ligne).
 *   : représente les lettres ASCII majuscules.
 *   : représente les caractères alphanumériques ASCII.
 *   : représente les chiffres hexadécimaux.
 *   : représente le caractère NULL  (le caractère de contrôle dont la valeur numérique est nulle).
 *   : tous les caractères (octets) qui ne sont pas dans.
 *   : tous les caractères (octets) qui ne sont pas dans.
 *   : tous les caractères (octets) qui ne sont pas dans.
 *   : tous les caractères (octets) qui ne sont pas dans.
 *   : tous les caractères (octets) qui ne sont pas dans.
 *   : tous les caractères (octets) qui ne sont pas dans code>%s.
 *   : tous les caractères (octets) qui ne sont pas dans.
 *   : tous les caractères (octets) qui ne sont pas dans.
 *   : tous les caractères (octets) qui ne sont pas dans.
 *   : tous les caractères (octets) qui ne sont pas dans.
 *   : (où x est n’importe quel caractère non alphanumérique) représente le caractère x. Ceci est la façon habituelle d’utiliser explicitement un caractère « magique » (ayant un sens de contrôle des motifs). Tout caractère non alphanumérique (même non magique) peut être précédé d’un   quand il doit représenter lui-même dans un motif.
 *   : représente l'ensemble des caractères présent dans l’union des caractères et des classes prédéfinies présents dans set. On peut également indiquer un intervalle borné de caractères en séparant les deux caractères qui bornent cet intervalle avec un tiret  . Par exemple   représente les chiffres du système octal, et   représente les chiffres du système octal plus les lettres ASCII minuscules plus le caractère ' '.
 *  : représente le complément de set, ou set est interprété suivant la définition ci-dessus.

Élément de motif (pattern item)
Un élément de motif peut être :

Notez que les motifs de frontière étaient présents mais non documentés dans Lua 5.1, et officiellement ajoutée dans Lua 5.2. Son implémentation dans Lua 5.2.1 n'a pas changée par rapport à ce qu'elle était dans Lua 5.1.0.
 * 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ère suivi d'un, qui correspond à 0 ou 1 occurrence d'un caractère de la classe ;
 * , 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) ;
 * , 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  correspond à une expression avec des parenthèses équilibrées.
 * , un motif de frontière ; fait correspondre 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. La frontière située à cette position et manipulée comme si elle était le caractère nul.

Motif (pattern)
Un motif est une séquence d'éléments de motif.

Un  au début d'un motif correspond au début de la ligne de la chaine traitée. Un  à la fin du motif correspond à la fin de la ligne de la chaîne traitée. Aux autres positions,  et   n'ont pas de sens particulier et représentent le caractère qui les constitue.

Captures
Un motif (pattern) peut contenir des sous-motifs entourés de parenthèses, qui décrivent des captures. Quand une correspondance réussit, la sous-chaine de la chaine qui correspond est stockée (capturée) pour usage ultérieur. Les captures sont numérotées dans l'ordre de leur parenthèse ouvrante. Par exemple, dans le motif, la partie de la chaine qui concorde avec   est stockée dans la première capture (et a donc le numéro 1) ; le caractère qui concorde avec   est stocké dans la capture numéro 2, et la partie qui concorde avec   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,  va correspondre à n'importe quelle pair de lettres en minuscule identiques, tandis que   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  sur la chaine , il y aura deux captures : 3 et 5.

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

Les fonctions,  , et   peuvent être disponibles mais sont dépréciées. Utilisez pairs, ipairs, et l'opérateur de longueur  à la place.

table.concat
Étant donné un tableau où tous les éléments sont des nombres ou des chaines, retourne.

La valeur par défaut de sep est la 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, retourne une chaine vide.

table.insert
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  ajoute x à la fin de la table t.

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

table.maxn
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 :

table.remove
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  supprime le dernier élément de la table t.

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

table.sort
Trie les éléments de la table dans l'ordre indiqué, sur place, de  à. Si comp est indiqué alors ce doit être une fonction qui reçoit deux éléments de la table et qui retourne vrai quand le premier est inférieur au second (ainsi  retournera true après le tri). Si comp n'est pas indiqué alors l'opérateur standard de comparaison  est utilisé.

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.addWarning
Adds a warning which is displayed above the preview when previewing an edit. is parsed as wikitext.

mw.allToString
Calls tostring on all arguments, then concatenates them with tabs as separators.

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

mw.getCurrentFrame
Returns the current frame object, typically the frame object from the most recent.

mw.incrementExpensiveFunctionCount
Adds one to the "expensive parser function" count, and throws an exception if it exceeds the limit (see ).

mw.isSubsting
Returns true if the current  is being substed, false otherwise. See Returning text above for discussion on differences when substing versus not substing.

mw.loadData
Sometimes a module needs large tables of data; for example, a general-purpose module to convert units of measure might need a large table of recognized units and their conversion factors. And sometimes these modules will be used many times in one page. Parsing the large data table for every  can use a significant amount of time. To avoid this issue,  is provided.

works like, with the following differences:


 * The loaded module is evaluated only once per page, rather than once per  call.
 * The loaded module is not recorded in.
 * The value returned from the loaded module must be a table. Other data types are not supported.
 * The returned table (and all subtables) may contain only booleans, numbers, strings, and other tables. Other data types, particularly functions, are not allowed.
 * The returned table (and all subtables) may not have a metatable.
 * All table keys must be booleans, numbers, or strings.
 * The table actually returned by  has metamethods that provide read-only access to the table returned by the module. Since it does not contain the data directly,   and   will work but other methods, including ,  , and the functions in the Table library, will not work correctly.

The hypothetical unit-conversion module mentioned above might store its code in "Module:Convert" and its data in "Module:Convert/data", and "Module:Convert" would use  to efficiently load the data.

mw.dumpObject
Serializes  to a human-readable representation, then returns the resulting string.

mw.log
Passes the arguments to mw.allToString, then appends the resulting string to the log buffer.

In the debug console, the function  is an alias for this function.

mw.logObject
Calls mw.dumpObject and appends the resulting string to the log buffer. If  is given, it will be added to the log buffer followed by an equals sign before the serialized string is appended (i.e. the logged text will be "prefix = object-string").

Frame object
The frame object is the interface to the parameters passed to, and to the parser.

frame.args
A table for accessing the arguments passed to the frame. For example, if a module is called from wikitext with

then  will return ,   will return  , and   (or  ) will return. It is also possible to iterate over arguments using  or.

Note that values in this table are always strings;  may be used to convert them to numbers, if necessary. Keys, however, are numbers even if explicitly supplied in the invocation:  gives string values   and   indexed by numeric keys   and.

As in MediaWiki template invocations, named arguments will have leading and trailing whitespace removed from both the name and the value before they are passed to Lua, whereas unnamed arguments will not have whitespace stripped.

For performance reasons,  uses a metatable, rather than directly containing the arguments. Argument values are requested from MediaWiki on demand. This means that most other table methods will not work correctly, including,  , and the functions in the Table library.

If preprocessor syntax such as template invocations and triple-brace arguments are included within an argument to #invoke, they will be expanded before being passed to Lua. If certain special tags written in XML notation, such as,  ,   and  , are included as arguments to #invoke, then these tags will be converted to "strip markers" — special strings which begin with a delete character (ASCII 127), to be replaced with HTML after they are returned from #invoke.

frame:callParserFunction

 * Note the use of named arguments.

Call a parser function, returning an appropriate string. Whenever possible, native Lua functions or Scribunto library functions should be preferred to this interface.

The following calls are approximately equivalent to the indicated wikitext:

Note that, as with frame:expandTemplate, the function name and arguments are not preprocessed before being passed to the parser function.

frame:expandTemplate

 * Note the use of named arguments.

This is transclusion. The call

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

does roughly the same thing from Lua that  does in wikitext. As in transclusion, if the passed title does not contain a namespace prefix it will be assumed to be in the Template: namespace.

Note that the title and arguments are not preprocessed before being passed into the template:

frame:extensionTag
This is equivalent to a call to frame:callParserFunction with function name  and with   prepended to.

frame:getParent
Called on the frame created by, returns the frame for the page that called. Called on that frame, returns nil.

For instance, if the template  contains the code , and a page transcludes that template and supplies arguments to it , calling   in Module:ModuleName will return.

frame:getTitle
Returns the title associated with the frame as a string. For the frame created by, this is the title of the module invoked.

frame:newChild

 * Note the use of named arguments.

Create a new Frame object that is a child of the current frame, with optional arguments and title.

This is mainly intended for use in the debug console for testing functions that would normally be called by. The number of frames that may be created at any one time is limited.

frame:preprocess
This expands wikitext in the context of the frame, i.e. templates, parser functions, and parameters such as  are expanded. Certain special tags written in XML-style notation, such as,  ,   and  , will be replaced with "strip markers" &mdash; special strings which begin with a delete character (ASCII 127), to be replaced with HTML after they are returned from.

If you are expanding a single template, use  instead of trying to construct a wikitext string to pass to this method. It's faster and less prone to error if the arguments contain pipe characters or other wikimarkup.

frame:getArgument
Gets an object for the specified argument, or nil if the argument is not provided.

The returned object has one method,, that returns the expanded wikitext for the argument.

frame:newParserValue
Returns an object with one method,, that returns the result of.

frame:newTemplateParserValue

 * Note the use of named arguments.

Returns an object with one method,, that returns the result of   called with the given arguments.

frame:argumentPairs
Same as. Included for backwards compatibility.

mw.hash.hashValue
Hashes a string value with the specified algorithm. Valid algorithms may be fetched using mw.hash.listAlgorithms.

mw.hash.listAlgorithms
Returns a list of supported hashing algorithms, for use in mw.hash.hashValue.

HTML library
is a fluent interface for building complex HTML from Lua. A mw.html object can be created using.

Functions documented as  are available on the global   table; functions documented as   are methods of an mw.html object (see  ).

A basic example could look like this:

mw.html.create
Creates a new mw.html object containing a  html element. You can also pass an empty string or nil as  in order to create an empty mw.html object.

can be a table with the following keys:


 * : Force the current tag to be self-closing, even if mw.html doesn't recognize it as self-closing
 * : Parent of the current mw.html instance (intended for internal usage)

mw.html:node
Appends a child mw.html node to the current mw.html instance. If a nil parameter is passed, this is a no-op. A node is a string representation of an html element.

mw.html:wikitext
Appends an undetermined number of wikitext strings to the mw.html object.

Note that this stops at the first nil item.

mw.html:newline
Appends a newline to the mw.html object.

mw.html:tag
Appends a new child node with the given  to the builder, and returns a mw.html instance representing that new node. The  parameter is identical to that of

mw.html:attr
Set an HTML attribute with the given  and   on the node. Alternatively a table holding name->value pairs of attributes to set can be passed. In the first form, a value of nil causes any attribute with the given name to be unset if it was previously set.

mw.html:getAttr
Get the value of a html attribute previously set using  with the given.

mw.html:addClass
Adds a class name to the node's class attribute. If a nil parameter is passed, this is a no-op.

mw.html:css
Set a CSS property with the given  and   on the node. Alternatively a table holding name->value pairs of properties to set can be passed. In the first form, a value of nil causes any property with the given name to be unset if it was previously set.

mw.html:cssText
Add some raw  to the node's style attribute. If a nil parameter is passed, this is a no-op.

mw.html:done
Returns the parent node under which the current node was created. Like jQuery.end, this is a convenience function to allow the construction of several child nodes to be chained together into a single statement.

mw.html:allDone
Like, but traverses all the way to the root node of the tree and returns it.

Language library
Language codes are described at language code. Many of MediaWiki's language codes are similar to IETF language tags, but not all MediaWiki language codes are valid IETF tags or vice versa.

Functions documented as  are available on the global   table; functions documented as   are methods of a language object (see  ).

mw.language.fetchLanguageName
The full name of the language for the given language code: native name (language autonym) by default, name translated in target language if a value is given for.

mw.language.fetchLanguageNames
Fetch the list of languages known to MediaWiki, returning a table mapping language code to language name.

By default the name returned is the language autonym; passing a language code for  returns all names in that language.

By default, only language names known to MediaWiki are returned; passing  for   will return all available languages (e.g. from Extension:CLDR), while passing   will include only languages having customized messages included with MediaWiki core or enabled extensions. To explicitly select the default,  may be passed.

mw.language.getContentLanguage
Returns a new language object for the wiki's default content language.

mw.language.getFallbacksFor
Returns a list of MediaWiki's fallback language codes for the specified code.

mw.language.isKnownLanguageTag
Returns true if a language code is known to MediaWiki.

A language code is "known" if it is a "valid built-in code" (i.e. it returns true for ) and returns a non-empty string for.

mw.language.isSupportedLanguage
Checks whether any localisation is available for that language code in MediaWiki.

A language code is "supported" if it is a "valid" code (returns true for ), contains no uppercase letters, and has a message file in the currently-running version of MediaWiki.

It is possible for a language code to be "supported" but not "known" (i.e. returning true for ). Also note that certain codes are "supported" despite  returning false.

mw.language.isValidBuiltInCode
Returns true if a language code is of a valid form for the purposes of internal customisation of MediaWiki.

The code may not actually correspond to any known language.

A language code is a "valid built-in code" if it is a "valid" code (i.e. it returns true for ); consists of only ASCII letters, numbers, and hyphens; and is at least two characters long.

Note that some codes are "supported" (i.e. returning true from ) even though this function returns false.

mw.language.isValidCode
Returns true if a language code string is of a valid form, whether or not it exists. This includes codes which are used solely for customisation via the MediaWiki namespace.

The code may not actually correspond to any known language.

A language code is valid if it does not contain certain unsafe characters (colons, single- or double-quotes, slashs, backslashs, angle brackets, ampersands, or ASCII NULs) and is otherwise allowed in a page title.

mw.language.new
Creates a new language object. Language objects do not have any publicly accessible properties, but they do have several methods, which are documented below.

There is a limit on the number of distinct language codes that may be used on a page. Exceeding this limit will result in errors.

mw.language:getCode
Returns the language code for this language object.

mw.language:getFallbackLanguages
Returns a list of MediaWiki's fallback language codes for this language object. Equivalent to.

mw.language:isRTL
Returns true if the language is written right-to-left, false if it is written left-to-right.

mw.language:lc
Converts the string to lowercase, honoring any special rules for the given language.

When the Ustring library is loaded, the mw.ustring.lower function is implemented as a call to.

mw.language:lcfirst
Converts the first character of the string to lowercase, as with lang:lc.

mw.language:uc
Converts the string to uppercase, honoring any special rules for the given language.

When the Ustring library is loaded, the mw.ustring.upper function is implemented as a call to.

mw.language:ucfirst
Converts the first character of the string to uppercase, as with lang:uc.

mw.language:caseFold
Converts the string to a representation appropriate for case-insensitive comparison. Note that the result may not make any sense when displayed.

mw.language:formatNum
Formats a number with grouping and decimal separators appropriate for the given language. Given 123456.78, this may produce "123,456.78", "123.456,78", or even something like "١٢٣٬٤٥٦٫٧٨" depending on the language and wiki configuration.

The  is a table of options, which can be:


 * : Set true to omit grouping separators.

mw.language:formatDate
Formats a date according to the given format string. If  is omitted, the default is the current time. The value for  must be a boolean or nil; if true, the time is formatted in the wiki's local time rather than in UTC.

The format string and supported values for  are identical to those for the #time parser function from Extension:ParserFunctions. Note however that backslashes may need to be doubled in a Lua string literal, since Lua also uses backslash as an escape character while wikitext does not:

mw.language:formatDuration
Breaks a duration in seconds into more human-readable units, e.g. 12345 to 3 hours, 25 minutes and 45 seconds, returning the result as a string.

, if given, is a table with values naming the interval units to use in the response. These include 'millennia', 'centuries', 'decades', 'years', 'weeks', 'days', 'hours', 'minutes', and 'seconds'.

mw.language:parseFormattedNumber
This takes a number as formatted by lang:formatNum and returns the actual number. In other words, this is basically a language-aware version of.

mw.language:convertPlural
This chooses the appropriate grammatical form from  (which must be a sequence table) or   based on the number. For example, in English you might use  or   to generate grammatically-correct text whether there is only 1 sock or 200 socks.

The necessary values for the sequence are language-dependent, see localization of magic words and translatewiki's FAQ on PLURAL for some details.

mw.language:convertGrammar

 * Note the different parameter order between the two aliases.  matches the order of the method of the same name on MediaWiki's Language object, while   matches the order of the parser function of the same name, documented at Special:MyLanguage/Help:Magic words.

This chooses the appropriate inflected form of  for the given inflection code.

The possible values for  and   are language-dependent, see Special:MyLanguage/Help:Magic words and translatewiki:Grammar for some details.

mw.language:gender
Chooses the string corresponding to the gender of, which may be "male", "female", or a registered user name.

mw.language:getArrow
Returns a Unicode arrow character corresponding to :


 * forwards: Either "→" or "←" depending on the directionality of the language.
 * backwards: Either "←" or "→" depending on the directionality of the language.
 * left: "←"
 * right: "→"
 * up: "↑"
 * down: "↓"

mw.language:getDir
Returns "ltr" or "rtl", depending on the directionality of the language.

mw.language:getDirMark
Returns a string containing either U+200E (the left-to-right mark) or U+200F (the right-to-left mark), depending on the directionality of the language and whether  is a true or false value.

mw.language:getDirMarkEntity
Returns "&amp;lrm;" or "&amp;rlm;", depending on the directionality of the language and whether  is a true or false value.

mw.language:getDurationIntervals
Breaks a duration in seconds into more human-readable units, e.g. 12345 to 3 hours, 25 minutes and 45 seconds, returning the result as a table mapping unit names to numbers.

, if given, is a table with values naming the interval units to use in the response. These include 'millennia', 'centuries', 'decades', 'years', 'days', 'hours', 'minutes', and 'seconds'.

Message library
This library is an interface to the localisation messages and the MediaWiki: namespace.

Functions documented as  are available on the global   table; functions documented as   are methods of a message object (see  ).

mw.message.new
Creates a new message object for the given message.

The message object has no properties, but has several methods documented below.

mw.message.newFallbackSequence
Creates a new message object for the given messages (the first one that exists will be used).

The message object has no properties, but has several methods documented below.

mw.message.newRawMessage
Creates a new message object, using the given text directly rather than looking up an internationalized message. The remaining parameters are passed to the new object's  method.

The message object has no properties, but has several methods documented below.

mw.message.rawParam
Wraps the value so that it will not be parsed as wikitext by.

mw.message.numParam
Wraps the value so that it will automatically be formatted as by. Note this does not depend on the Language library actually being available.

mw.message.getDefaultLanguage
Returns a Language object for the default language.

mw.message:params
Add parameters to the message, which may be passed as individual arguments or as a sequence table. Parameters must be numbers, strings, or the special values returned by mw.message.numParam or mw.message.rawParam. If a sequence table is used, parameters must be directly present in the table; references using the __index metamethod will not work.

Returns the  object, to allow for call chaining.

mw.message:rawParams
Like params, but has the effect of passing all the parameters through mw.message.rawParam first.

Returns the  object, to allow for call chaining.

mw.message:numParams
Like params, but has the effect of passing all the parameters through mw.message.numParam first.

Returns the  object, to allow for call chaining.

mw.message:inLanguage
Specifies the language to use when processing the message. may be a string or a table with a  method (i.e. a Language object).

The default language is the one returned by.

Returns the  object, to allow for call chaining.

mw.message:useDatabase
Specifies whether to look up messages in the MediaWiki: namespace (i.e. look in the database), or just use the default messages distributed with MediaWiki.

The default is true.

Returns the  object, to allow for call chaining.

mw.message:plain
Substitutes the parameters and returns the message wikitext as-is. Template calls and parser functions are intact.

mw.message:exists
Returns a boolean indicating whether the message key exists.

mw.message:isBlank
Returns a boolean indicating whether the message key has content. Returns true if the message key does not exist or the message is the empty string.

mw.message:isDisabled
Returns a boolean indicating whether the message key is disabled. Returns true if the message key does not exist or if the message is the empty string or the string "-".

mw.site.currentVersion
A string holding the current version of MediaWiki.

mw.site.scriptPath
The value of.

mw.site.server
The value of.

mw.site.siteName
The value of.

mw.site.stylePath
The value of.

mw.site.namespaces
Table holding data for all namespaces, indexed by number.

The data available is:


 * id: Namespace number.
 * name: Local namespace name.
 * canonicalName: Canonical namespace name.
 * displayName: Set on namespace 0, the name to be used for display (since the name is often the empty string).
 * hasSubpages: Whether subpages are enabled for the namespace.
 * hasGenderDistinction: Whether the namespace has different aliases for different genders.
 * isCapitalized: Whether the first letter of pages in the namespace is capitalized.
 * isContent: Whether this is a content namespace.
 * isIncludable: Whether pages in the namespace can be transcluded.
 * isMovable: Whether pages in the namespace can be moved.
 * isSubject: Whether this is a subject namespace.
 * isTalk: Whether this is a talk namespace.
 * defaultContentModel: The default content model for the namespace, as a string.
 * aliases: List of aliases for the namespace.
 * subject: Reference to the corresponding subject namespace's data.
 * talk: Reference to the corresponding talk namespace's data.
 * associated: Reference to the associated namespace's data.

A metatable is also set that allows for looking up namespaces by name (localized or canonical). For example, both  and   will return information about the Project namespace.

mw.site.contentNamespaces
Table holding just the content namespaces, indexed by number. See mw.site.namespaces for details.

mw.site.subjectNamespaces
Table holding just the subject namespaces, indexed by number. See mw.site.namespaces for details.

mw.site.talkNamespaces
Table holding just the talk namespaces, indexed by number. See mw.site.namespaces for details.

mw.site.stats
Table holding site statistics. Available statistics are:


 * pages: Number of pages in the wiki.
 * articles: Number of articles in the wiki.
 * files: Number of files in the wiki.
 * edits: Number of edits in the wiki.
 * views: Number of views in the wiki. Not available if is set.
 * users: Number of users in the wiki.
 * activeUsers: Number of active users in the wiki.
 * admins: Number of users in group 'sysop' in the wiki.

mw.site.stats.pagesInCategory


Gets statistics about the category. If  is unspecified, nil, or "*", returns a table with the following properties:


 * all: Total pages, files, and subcategories.
 * subcats: Number of subcategories.
 * files: Number of files.
 * pages: Number of pages.

If  is one of the above keys, just the corresponding value is returned instead.

Each new category queried will increment the expensive function count.

mw.site.stats.pagesInNamespace
Returns the number of pages in the given namespace (specify by number).

mw.site.stats.usersInGroup
Returns the number of users in the given group.

mw.site.interwikiMap
Returns a table holding data about available interwiki prefixes. If  is the string "local", then only data for local interwiki prefixes is returned. If  is the string "!local", then only data for non-local prefixes is returned. If no filter is specified, data for all prefixes is returned. A "local" prefix in this context is one that is for the same project. For example, on the English Wikipedia, other-language Wikipedias are considered local, while Wiktionary and such are not.

Keys in the table returned by this function are interwiki prefixes, and the values are subtables with the following properties:


 * prefix - the interwiki prefix.
 * url - the URL that the interwiki points to. The page name is represented by the parameter $1.
 * isProtocolRelative - a boolean showing whether the URL is protocol-relative.
 * isLocal - whether the URL is for a site in the current project.
 * isCurrentWiki - whether the URL is for the current wiki.
 * isTranscludable - whether pages using this interwiki prefix are transcludable. This requires scary transclusion, which is disabled on Wikimedia wikis.
 * isExtraLanguageLink - whether the interwiki is listed in.
 * displayText - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the display text shown for the interlanguage link. Nil if not specified.
 * tooltip - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the tooltip text shown when users hover over the interlanguage link. Nil if not specified.

Text library
The text library provides some common text processing functions missing from the String library and the Ustring library. These functions are safe for use with UTF-8 strings.

mw.text.decode
Replaces HTML entities in the string with the corresponding characters.

If  is omitted or false, the only named entities recognized are '&amp;lt;', '&amp;gt;', '&amp;amp;', '&amp;quot;', and '&amp;nbsp;'. Otherwise, the list of HTML5 named entities to recognize is loaded from PHP's function.

mw.text.encode
Replaces characters in a string with HTML entities. Characters '<', '>', '&', '"', and the non-breaking space are replaced with the appropriate named entities; all others are replaced with numeric entities.

If  is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in. The default charset is  (the space at the end is the non-breaking space, U+00A0).

mw.text.jsonDecode
Decodes a JSON string. is 0 or a combination (use ) of the flags   and.

Normally JSON's zero-based arrays are renumbered to Lua one-based sequence tables; to prevent this, pass.

To relax certain requirements in JSON, such as no terminal comma in arrays or objects, pass. This is not recommended.

Limitations:


 * Decoded JSON arrays may not be Lua sequences if the array contains null values.
 * JSON objects will drop keys having null values.
 * It is not possible to directly tell whether the input was a JSON array or a JSON object with sequential integer keys.
 * A JSON object having sequential integer keys beginning with 1 will decode to the same table structure as a JSON array with the same values, despite these not being at all equivalent, unless  is used.

mw.text.jsonEncode
Encode a JSON string. Errors are raised if the passed value cannot be encoded in JSON. is 0 or a combination (use ) of the flags   and.

Normally Lua one-based sequence tables are encoded as JSON zero-based arrays; when  is set in , zero-based sequence tables are encoded as JSON arrays.

Limitations:


 * Empty tables are always encoded as empty arrays, not empty objects.
 * Sequence tables cannot be encoded as JSON objects without adding a "dummy" element.
 * To produce objects or arrays with nil values, a tricky implementation of the  metamethod is required.
 * A Lua table having sequential integer keys beginning with 0 will encode as a JSON array, the same as a Lua table having integer keys beginning with 1, unless  is used.
 * When both a number and the string representation of that number are used as keys in the same table, behavior is unspecified.

mw.text.killMarkers
Removes all MediaWiki strip markers from a string.

mw.text.listToText
Join a list, prose-style. In other words, it's like  but with a different separator before the final item.

The default separator is taken from MediaWiki:comma-separator in the wiki's content language, and the default conjuction is MediaWiki:and concatenated with MediaWiki:word-separator.

Examples, using the default values for the messages:

-- Returns the empty string mw.text.listToText( {} ) -- Returns "1" mw.text.listToText( { 1 } ) -- Returns "1 and 2" mw.text.listToText( { 1, 2 } ) -- Returns "1, 2, 3, 4 and 5" mw.text.listToText( { 1, 2, 3, 4, 5 } ) -- Returns "1; 2; 3; 4 or 5" mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' or ' )

mw.text.nowiki
Replaces various characters in the string with HTML entities to prevent their interpretation as wikitext. This includes:


 * The following characters: '"', '&', "'", '<', '=', '>', '[', ']', '{', '|', '}'
 * The following characters at the start of the string or immediately after a newline: '#', '*', ':', ';', space, tab ('\t')
 * Blank lines will have one of the associated newline or carriage return characters escaped
 * "" at the start of the string or immediately after a newline will have the first '-' escaped
 * "__" will have one underscore escaped
 * "://" will have the colon escaped
 * A whitespace character following "ISBN", "RFC", or "PMID" will be escaped

mw.text.split
Splits the string into substrings at boundaries matching the Ustring pattern. If  is specified and true,   will be interpreted as a literal string rather than as a Lua pattern (just as with the parameter of the same name for  ). Returns a table containing the substrings.

For example,  would return a table.

If  matches the empty string,   will be split into individual characters.

mw.text.gsplit
Returns an iterator function that will iterate over the substrings that would be returned by the equivalent call to.

mw.text.tag

 * Note the use of named arguments.

Generates an HTML-style tag for.

If  is given, it must be a table with string keys. String and number values are used as the value of the attribute; boolean true results in the key being output as an HTML5 valueless parameter; boolean false skips the key entirely; and anything else is an error.

If  is not given (or is nil), only the opening tag is returned. If  is boolean false, a self-closed tag is returned. Otherwise it must be a string or number, in which case that content is enclosed in the constructed opening and closing tag. Note the content is not automatically HTML-encoded; use mw.text.encode if needed.

For properly returning extension tags such as, use frame:extensionTag instead.

mw.text.trim
Remove whitespace or other characters from the beginning and end of a string.

If  is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in. The default charset is ASCII whitespace,.

mw.text.truncate
Truncates  to the specified length, adding   if truncation was performed. If length is positive, the end of the string will be truncated; if negative, the beginning will be removed. If  is given and true, the resulting string including ellipsis will not be longer than the specified length.

The default value for  is taken from MediaWiki:ellipsis in the wiki's content language.

Examples, using the default "..." ellipsis:

-- Returns "foobarbaz" mw.text.truncate( "foobarbaz", 9 ) -- Returns "fooba..." mw.text.truncate( "foobarbaz", 5 ) -- Returns "...arbaz" mw.text.truncate( "foobarbaz", -5 ) -- Returns "foo..." mw.text.truncate( "foobarbaz", 6, nil, true ) -- Returns "foobarbaz", because that's shorter than "foobarba..." mw.text.truncate( "foobarbaz", 8 )

mw.text.unstripNoWiki
Replaces MediaWiki &lt;nowiki&gt; strip markers with the corresponding text. Other types of strip markers are not changed.

mw.text.unstrip
Equivalent to.

This no longer reveals the HTML behind special page transclusion, &lt;ref&gt; tags, and so on as it did in earlier versions of Scribunto.

mw.title.equals
Test for whether two titles are equal. Note that fragments are ignored in the comparison.

mw.title.compare
Returns -1, 0, or 1 to indicate whether the title  is less than, equal to, or greater than title.

This compares titles by interwiki prefix (if any) as strings, then by namespace number, then by the unprefixed title text as a string. These string comparisons use Lua's standard  operator.

mw.title.getCurrentTitle
Returns the title object for the current page.

mw.title.new


Creates a new title object.

If a number  is given, an object is created for the title with that page_id. The title referenced will be counted as linked from the current page. If the page_id does not exist, returns nil. The expensive function count will be incremented if the title object created is not for a title that has already been loaded.

If a string  is given instead, an object is created for that title (even if the page does not exist). If the text string does not specify a namespace,  (which may be any key found in  ) will be used. If the text is not a valid title, nil is returned.

mw.title.makeTitle
Creates a title object with title  in namespace , optionally with the specified   and   prefix. may be any key found in. If the resulting title is not valid, returns nil.

Note that, unlike, this method will always apply the specified namespace. For example,  will create an object for the page Template:Module:Foo, while   will create an object for the page Module:Foo.

Title objects
A title object has a number of properties and methods. Most of the properties are read-only.

Note that fields ending with  return titles as string values whereas the fields ending with   return title objects.


 * id: The page_id. 0 if the page does not exist., and the page will be recorded as a link.
 * interwiki: The interwiki prefix, or the empty string if none.
 * namespace: The namespace number.
 * fragment: The fragment, or the empty string. May be assigned.
 * nsText: The text of the namespace for the page.
 * subjectNsText: The text of the subject namespace for the page.
 * text: The title of the page, without the namespace or interwiki prefixes.
 * prefixedText: The title of the page, with the namespace and interwiki prefixes.
 * fullText: The title of the page, with the namespace and interwiki prefixes and the fragment.
 * rootText: If this is a subpage, the title of the root page without prefixes. Otherwise, the same as.
 * baseText: If this is a subpage, the title of the page it is a subpage of without prefixes. Otherwise, the same as.
 * subpageText: If this is a subpage, just the subpage name. Otherwise, the same as.
 * canTalk: Whether the page for this title could have a talk page.
 * exists: Whether the page exists. Alias for file.exists for Media-namespace titles. For File-namespace titles this checks the existence of the file description page, not the file itself., and the page will be recorded as a link.
 * file, fileExists: See below.
 * isContentPage: Whether this title is in a content namespace.
 * isExternal: Whether this title has an interwiki prefix.
 * isLocal: Whether this title is in this project. For example, on the English Wikipedia, any other Wikipedia is considered "local" while Wiktionary and such are not.
 * isRedirect: Whether this is the title for a page that is a redirect., and the page will be recorded as a link.
 * isSpecialPage: Whether this is the title for a possible special page (i.e. a page in the Special: namespace).
 * isSubpage: Whether this title is a subpage of some other title.
 * isTalkPage: Whether this is a title for a talk page.
 * isSubpageOf( title2 ): Whether this title is a subpage of the given title.
 * inNamespace( ns ): Whether this title is in the given namespace. Namespaces may be specified by anything that is a key found in.
 * inNamespaces( ... ): Whether this title is in any of the given namespaces. Namespaces may be specified by anything that is a key found in.
 * hasSubjectNamespace( ns ): Whether this title's subject namespace is in the given namespace. Namespaces may be specified by anything that is a key found in.
 * contentModel: The content model for this title, as a string., and the page will be recorded as a link.
 * basePageTitle: The same as.
 * rootPageTitle: The same as.
 * talkPageTitle: The same as, or nil if this title cannot have a talk page.
 * subjectPageTitle: The same as.
 * redirectTarget: Returns a title object of the target of the redirect page if the page is a redirect and the page exists, returns false otherwise.
 * protectionLevels: The page's protection levels. This is a table with keys corresponding to each action (e.g., "edit" and "move"). The table values are arrays, the first item of which is a string containing the protection level. If the page is unprotected, either the table values or the array items will be nil..
 * subPageTitle( text ): The same as.
 * partialUrl: Returns  encoded as it would be in a URL.
 * fullUrl( query, proto ): Returns the full URL (with optional query table/string) for this title.  may be specified to control the scheme of the resulting url: "http", "https", "relative" (the default), or "canonical".
 * localUrl( query ): Returns the local URL (with optional query table/string) for this title.
 * canonicalUrl( query ): Returns the canonical URL (with optional query table/string) for this title.
 * getContent: Returns the (unparsed) content of the page, or nil if there is no page. The page will be recorded as a transclusion.

Title objects may be compared using Relational operators. will return.

File metadata
Title objects representing a page in the File or Media namespace will have a property called. This is a table, structured as follows:


 * exists: Whether the file exists. It will be recorded as an image usage. The  property on a Title object exists for backwards compatibility reasons and is an alias for this property. If this is false, all other file properties will be nil.
 * width: The width of the file. If the file contains multiple pages, this is the width of the first page.
 * height: The height of the file. If the file contains multiple pages, this is the height of the first page.
 * pages: If the file format supports multiple pages, this is a table containing tables for each page of the file; otherwise, it is nil. The # operator can be used to get the number of pages in the file. Each individual page table contains a width and height property.
 * size: The size of the file in bytes.
 * mimeType: The MIME type of the file.

Expensive properties
The properties id, isRedirect, exists, and contentModel require fetching data about the title from the database. For this reason, the expensive function count is incremented the first time one of them is accessed for a page other than the current page. Subsequent accesses of any of these properties for that page will not increment the expensive function count again.

Other properties marked as expensive will always increment the expensive function count the first time they are accessed for a page other than the current page.

mw.uri.encode
Percent-encodes the string. The default type,, encodes spaces using '+' for use in query strings;   encodes spaces as %20; and   encodes spaces as '_'.

Note that the "WIKI" format is not entirely reversible, as both spaces and underscores are encoded as '_'.

mw.uri.decode
Percent-decodes the string. The default type,, decodes '+' to space;   does not perform any extra decoding; and   decodes '_' to space.

mw.uri.anchorEncode
Encodes a string for use in a MediaWiki URI fragment.

mw.uri.buildQueryString
Encodes a table as a URI query string. Keys should be strings; values may be strings or numbers, sequence tables, or boolean false.

mw.uri.parseQueryString
Decodes the query string  to a table. Keys in the string without values will have a value of false; keys repeated multiple times will have sequence tables as values; and others will have strings as values.

The optional numerical arguments  and   can be used to specify a substring of   to be parsed, rather than the entire string. is the position of the first character of the substring, and defaults to 1. is the position of the last character of the substring, and defaults to the length of the string. Both  and   can be negative, as in string.sub.

mw.uri.canonicalUrl
Returns a URI object for the canonical URL for a page, with optional query string/table.

mw.uri.fullUrl
Returns a URI object for the full URL for a page, with optional query string/table.

mw.uri.localUrl
Returns a URI object for the local URL for a page, with optional query string/table.

mw.uri.new
Constructs a new URI object for the passed string or table. See the description of URI objects for the possible fields for the table.

mw.uri.validate
Validates the passed table (or URI object). Returns a boolean indicating whether the table was valid, and on failure a string explaining what problems were found.

URI object
The URI object has the following fields, some or all of which may be nil:


 * protocol: String protocol/scheme
 * user: String user
 * password: String password
 * host: String host name
 * port: Integer port
 * path: String path
 * query: A table, as from mw.uri.parseQueryString
 * fragment: String fragment.

The following properties are also available:
 * userInfo: String user and password
 * hostPort: String host and port
 * authority: String user, password, host, and port
 * queryString: String version of the query table
 * relativePath: String path, query string, and fragment

will give the URI string.

Methods of the URI object are:

mw.uri:parse
Parses a string into the current URI object. Any fields specified in the string will be replaced in the current object; fields not specified will keep their old values.

mw.uri:clone
Makes a copy of the URI object.

mw.uri:extend
Merges the parameters table into the object's query table.

Ustring library
The ustring library is intended to be a direct reimplementation of the standard String library, except that the methods operate on characters in UTF-8 encoded strings rather than bytes.

Most functions will raise an error if the string is not valid UTF-8; exceptions are noted.

mw.ustring.maxPatternLength
The maximum allowed length of a pattern, in bytes.

mw.ustring.maxStringLength
The maximum allowed length of a string, in bytes.

mw.ustring.byte
Returns individual bytes; identical to string.byte.

mw.ustring.byteoffset
Returns the byte offset of a character in the string. The default for both  and   is 1. may be negative, in which case it counts from the end of the string.

The character at  == 1 is the first character starting at or after byte  ; the character at   == 0 is the first character starting at or before byte. Note this may be the same character. Greater or lesser values of  are calculated relative to these.

mw.ustring.char
Much like string.char, except that the integers are Unicode codepoints rather than byte values.

mw.ustring.codepoint
Much like string.byte, except that the return values are codepoints and the offsets are characters rather than bytes.

mw.ustring.find
Much like string.find, except that the pattern is extended as described in Ustring patterns and the  offset is in characters rather than bytes.

mw.ustring.format
Identical to string.format. Widths and precisions for strings are expressed in bytes, not codepoints.

mw.ustring.gcodepoint
Returns three values for iterating over the codepoints in the string. defaults to 1, and  to -1. This is intended for use in the iterator form of :

mw.ustring.gmatch
Much like string.gmatch, except that the pattern is extended as described in Ustring patterns.

mw.ustring.gsub
Much like string.gsub, except that the pattern is extended as described in Ustring patterns.

mw.ustring.isutf8
Returns true if the string is valid UTF-8, false if not.

mw.ustring.len
Returns the length of the string in codepoints, or nil if the string is not valid UTF-8.

See string.len for a similar function that uses byte length rather than codepoints.

mw.ustring.lower
Much like string.lower, except that all characters with lowercase to uppercase definitions in Unicode are converted.

If the Language library is also loaded, this will instead call lc on the default language object.

mw.ustring.match
Much like string.match, except that the pattern is extended as described in Ustring patterns and the  offset is in characters rather than bytes.

mw.ustring.rep
Identical to string.rep.

mw.ustring.sub
Much like string.sub, except that the offsets are characters rather than bytes.

mw.ustring.toNFC
Converts the string to Normalization Form C. Returns nil if the string is not valid UTF-8.

mw.ustring.toNFD
Converts the string to Normalization Form D. Returns nil if the string is not valid UTF-8.

mw.ustring.upper
Much like string.upper, except that all characters with uppercase to lowercase definitions in Unicode are converted.

If the Language library is also loaded, this will instead call uc on the default language object.

Ustring patterns
Patterns in the ustring functions use the same syntax as the String library patterns. The major difference is that the character classes are redefined in terms of Unicode character properties:


 *  : represents all characters with General Category "Letter".
 *  : represents all characters with General Category "Control".
 *  : represents all characters with General Category "Decimal Number".
 *  : represents all characters with General Category "Lowercase Letter".
 *  : represents all characters with General Category "Punctuation".
 *  : represents all characters with General Category "Separator", plus tab, linefeed, carriage return, vertical tab, and form feed.
 *  : represents all characters with General Category "Uppercase Letter".
 *  : represents all characters with General Category "Letter" or "Decimal Number".
 *  : adds fullwidth character versions of the hex digits.

In all cases, characters are interpreted as Unicode characters instead of bytes, so ranges such as, patterns such as  , and quantifiers applied to multibyte characters will work correctly. Empty captures will capture the position in code points rather than bytes.

Loadable libraries
These libraries are not included by default, but if needed may be loaded using.

bit32
This emulation of the Lua 5.2  library may be loaded using

bit32 = require( 'bit32' )

The bit32 library provides bitwise operations on unsigned 32-bit integers. Input numbers are truncated to integers (in an unspecified manner) and reduced modulo 232 so the value is in the range 0 to 232−1; return values are also in this range.

When bits are numbered (as in bit32.extract), 0 is the least-significant bit (the one with value 20) and 31 is the most-significant (the one with value 231).

bit32.band
Returns the bitwise AND of its arguments: the result has a bit set only if that bit is set in all of the arguments.

If given zero arguments, the result has all bits set.

bit32.bnot
Returns the bitwise complement of.

bit32.bor
Returns the bitwise OR of its arguments: the result has a bit set if that bit is set in any of the arguments.

If given zero arguments, the result has all bits clear.

bit32.btest
Equivalent to

bit32.bxor
Returns the bitwise XOR of its arguments: the result has a bit set if that bit is set in an odd number of the arguments.

If given zero arguments, the result has all bits clear.

bit32.extract
Extracts  bits from , starting with bit. Accessing bits outside of the range 0 to 31 is an error.

If not specified, the default for  is 1.

bit32.replace
Replaces  bits in , starting with bit  , with the low   bits from. Accessing bits outside of the range 0 to 31 is an error.

If not specified, the default for  is 1.

bit32.lshift
Returns the number  shifted   bits to the left. This is a logical shift: inserted bits are 0. This is generally equivalent to multiplying by 2undefined.

Note that a displacement over 31 will result in 0.

bit32.rshift
Returns the number  shifted   bits to the right. This is a logical shift: inserted bits are 0. This is generally equivalent to dividing by 2undefined.

Note that a displacement over 31 will result in 0.

bit32.arshift
Returns the number  shifted   bits to the right. This is an arithmetic shift: if  is positive, the inserted bits will be the same as bit 31 in the original number.

Note that a displacement over 31 will result in 0 or 4294967295.

bit32.lrotate
Returns the number  rotated   bits to the left.

Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.

bit32.rrotate
Returns the number  rotated   bits to the right.

Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.

libraryUtil
This library contains methods useful when implementing Scribunto libraries. It may be loaded using

libraryUtil = require( 'libraryUtil' )

libraryUtil.checkType
Raises an error if  does not match. In addition, no error will be raised if  is nil and   is true.

is the name of the calling function, and  is the position of the argument in the argument list. These are used in formatting the error message.

libraryUtil.checkTypeMulti
Raises an error if  does not match any of the strings in the array.

This is for arguments that have more than one valid type.

libraryUtil.checkTypeForIndex
Raises an error if  does not match.

This is intended for use in implementing a  metamethod.

libraryUtil.checkTypeForNamedArg
Raises an error if  does not match. In addition, no error will be raised if  is nil and   is true.

This is intended to be used as an equivalent to  in methods called using Lua's "named argument" syntax,.

libraryUtil.makeCheckSelfFunction
This is intended for use in implementing "methods" on object tables that are intended to be called with the  syntax. It returns a function that should be called at the top of these methods with the  argument and the method name, which will raise an error if that   object is not.

This function will generally be used in a library's constructor function, something like this:

function myLibrary.new local obj = {} local checkSelf = libraryUtil.makeCheckSelfFunction( 'myLibrary', 'obj', obj, 'myLibrary object' ) function obj:method checkSelf( self, 'method' ) end function obj:method2 checkSelf( self, 'method2' ) end return obj end

luabit
The luabit library modules "bit" and "hex" may be loaded using

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

Note that the bit32 library contains the same operations as "luabit.bit", and the operations in "luabit.hex" may be performed using  and.

The luabit module "noki" is not available, as it is entirely useless in Scribunto. The luabit module "utf8" is also not available, as it was considered redundant to the Ustring library.

ustring
The pure-Lua backend to the Ustring library may be loaded using

ustring = require( 'ustring' )

In all cases the Ustring library should be used instead, as that replaces many of the slower and more memory-intensive operations with callbacks into PHP code.

Extension libraries (mw.ext)
The following MediaWiki extensions provide additional Scribunto libraries:


 * Wikibase Client – provides access to Wikidata. See Extension:Wikibase Client/Lua.
 * Semantic Scribunto - provides native support for the Scribunto extension to Semantic MediaWiki extension.
 * tabular data - provides access to localizable data tables and geojson maps stored on Commons.

See also the lists of extensions using the ScribuntoExternalLibraries and ScribuntoExternalLibraryPaths hooks.

Planned Scribunto libraries
These libraries are planned, or are in Gerrit pending review.


 * (none at this time)

Changed functions
The following functions have been modified:
 * setfenv
 * getfenv: May not be available, depending on the configuration. If available, attempts to access parent environments will fail.
 * getmetatable: Works on tables only to prevent unauthorized access to parent environments.
 * tostring: Pointer addresses of tables and functions are not provided. This is to make memory corruption vulnerabilities more difficult to exploit.
 * pairs
 * ipairs: Support for the __pairs and __ipairs metamethods (added in Lua 5.2) has been added.
 * pcall
 * xpcall: Certain internal errors cannot be intercepted.
 * require: Can fetch certain built-in modules distributed with Scribunto, as well as modules present in the Module namespace of the wiki. To fetch wiki modules, use the full page name including the namespace. Cannot otherwise access the local filesystem.

Removed functions and packages
The following packages are mostly removed. Only those functions listed are available:
 * package.*: Filesystem and C library access has been removed. Available functions and tables are:
 * package.loaded
 * package.preload
 * package.loaders: Loaders which access the local filesystem or load C libraries are not present. A loader for Module-namespace pages is added.
 * package.seeall


 * os.*: There are some insecure functions in here, such as os.execute, which can't be allowed. Available functions are:
 * os.clock
 * os.date
 * os.difftime
 * os.time


 * debug.*: Most of the functions are insecure. Available functions are:
 * debug.traceback

The following functions and packages are not available:
 * collectgarbage
 * module
 * coroutine.*: No application is known for us, so it has not been reviewed for security.
 * dofile
 * loadfile
 * io.*, file.*: Allows local filesystem access, which is insecure.
 * load
 * loadstring: These were omitted to allow for static analysis of the Lua source code. Also, allowing these would allow Lua code to be added directly to article and template pages, which was not desired for usability reasons.
 * print: This was discussed on wikitech-l and it was decided that it should be omitted in favour of return values, to improve code quality. If necessary, mw.log may be used to output information to the debug console.
 * string.dump: May expose private data from parent environments.

Additional caveats

 * Referential data structures: Circular data structures and data structures where the same node may be reached by more than one path cannot be correctly sent to PHP. Attempting to do so will cause undefined behavior. This includes (but is not limited to) returning such data structures from the module called by  and passing such data structures as parameters to Scribunto library functions that are implemented as callbacks into PHP. Such data structures may be used freely within Lua, including as the return values of modules loaded with.

Writing Scribunto libraries
This information is useful to developers writing additional Scribunto libraries, whether for inclusion in Scribunto itself or for providing an interface for their own extensions.

A Scribunto library will generally consist of five parts:


 * The PHP portion of the library.
 * The Lua portion of the library.
 * The PHP portion of the test cases.
 * The Lua portion of the test cases.
 * The documentation.

Existing libraries serve as a good example.

Library
The PHP portion of the library is a class that must extend. See the documentation for that class for implementation details. In the Scribunto extension, this file should be placed in, and a mapping added to. Other extensions should use the  hook. In either case, the key should match the Lua module name ("mw.name" for libraries in Scribunto, or "mw.ext.name" for extension libraries).

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

The module in  (load this with  ) contains some functions that may be helpful.

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

Test cases
The Scribunto extension includes a base class for test cases,, which will run the tests against both the LuaSandbox and LuaStandalone engines. The library's test case should extend this class, and should not override. In the Scribunto extension, the test case should be in  and added to the array in   (in  ); extensions should add the test case in their own   hook function, probably conditional on whether   is set.

Most of the time, all that is needed to make the test case is this:

class ClassNameTest extends Scribunto_LuaEngineTestBase { protected static $moduleName = 'ClassNameTest'; function getTestModules { return parent::getTestModules + array(             'ClassNameTest' => __DIR__ . '/ClassNameTests.lua';          ); } }

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


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

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

local testframework = require 'Module:TestFramework' return testframework.getTestProvider( {    -- Tests go here } )

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


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

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


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

Test cases in another extension
There are (at least) two ways to run PHPUnit tests:


 * 1) Run phpunit against core, allowing the tests/phpunit/suites/ExtensionsTestSuite.php to find the extension's tests using the UnitTestsList hook. If your extension's test class names all contain a unique component (e.g. the extension's name), the   option may be used to run only your extension's tests.
 * 2) Run phpunit against the extension directory, where it will pick up any file ending in "Test.php".

Either of these will work fine if Scribunto is loaded in LocalSettings.php. And it is easy for method #1 to work if Scribunto is not loaded, as the UnitTestsList hook can easily be written to avoid returning the Scribunto test when  is not set.

But Jenkins uses method #2. For Jenkins to properly run the tests, you will need to add Scribunto as a dependency for your extension. See for an example of how this is done.

If for some reason you need the tests to be able to run using method #2 without Scribunto loaded, one workaround is to add this check to the top of your unit test file:

if ( !isset( $GLOBALS['wgAutoloadClasses']['Scribunto_LuaEngineTestBase'] ) ) { return; }

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

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

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