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

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Extension:Scribunto/Lua reference manual and the translation is 91% complete.

Outdated translations are marked like this.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Esperanto • ‎Tiếng Việt • ‎asturianu • ‎dansk • ‎español • ‎français • ‎italiano • ‎magyar • ‎polski • ‎português do Brasil • ‎русский • ‎українська • ‎עברית • ‎ဖၠုံလိက် • ‎မြန်မာဘာသာ • ‎中文 • ‎日本語 • ‎한국어
Raccourcis :
Lua manual
LUAREF

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

Contents

Introduction

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 :

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

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

return p

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

{{#invoke:Bananas|hello}}

Vous pouvez remplacer « Bananas » par le nom de module de votre choix. Ceci va appeler la fonction « hello » exportée par ce module. Le code {{#invoke:Bananas|hello}} 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 Lua contenant des fonctions qui peuvent être appelées via la syntaxe {{#invoke:}}. Généralement, comme cela a été montré ci-dessus, une variable locale est déclarée associée à une table, des fonctions sont ajoutées à 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 {{#invoke:}}, mais les fonctions globales resteront accessibles depuis d'autres modules via la fonction require(). 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 {{#invoke:}} reçoivent un seul paramètre, un objet frame. Les paramètres transmis par {{#invoke:}} sont dans la table args de l'objet frame. Il est aussi possible d'accéder aux paramètres transmis au modèle contenant {{#invoke:}} en utilisant la fonction frame:getParent() pour accéder à la table args 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 remplacement du {{#invoke:}}.

À 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 ~~~~). Ainsi un module ne peut pas utiliser ces fonctionnalités dans sa sortie. Par exemple si un module retourne "Hello, [[world]]! {{welcome}}", la page contiendra "Hello, world! {{welcome}}".

D'autre part, subst est géré plus tôt dans le traitement d'une page, donc avec {{subst:#invoke:}} seules les 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 "/Documentation", 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/Documentation".

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 $1. 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 {{#invoke:}}). 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 $1. 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 $1. 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 $1 ; 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. La catégorisation peut se faire dans la documentation à l'intérieur des balises <includeonly>...</includeonly>. Elle ne sera ainsi appliquée qu'au module et non à la sous-page de documentation elle-même.

Le langage

Entités

Les Noms (aussi appelés identifiants) dans Lua peuvent être formés de n'importe quelle séquence ASCII de lettres (de A à Z ou de a à z), chiffres (de 0 à 9) 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 :

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

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é.

-- Un commentaire en Lua commence avec un double-tiret et se termine à la fin de la ligne
--[[ un commentaire multi-ligne commence avec un double tiret et un double crochet ouvrant  et le bloc se finit avec un double crochet  ]]
--[=[ Des commentaires de ce genre contiennent d'autres commentaires en imbrication. ]=]
--[==[ Des commentaires de cette sorte contiennent 
      --[===[ de longs --[=[commentaires]=] --inclus
        ]===] plusieurs fois, même si chacun d'entre eux n'est pas
      --[[ borné par des crochets longs appareillés! ]===]
  ]==]

Types et valeurs

Lua est un langage typé dynamiquement. Cela signifie que les variables n'ont pas de type déclaré à l'origine (numérique, chaîne, booléen etc.), seules les valeurs en sont porteuses. Il n'y a aucune définition de type dans ce langage, chaque valeur transportant son propre type qui peut être défini de façon particulière par l'utilisateur.

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

La fonction tostring() convertit une valeur en chaine. La chaine est la base de Lua (détails plus loin, paragraphe sur la table "string" section Méta-table).
La fonction tonumber() convertit une valeur en nombre si possible, et retourne sinon la valeur nil qui est un type spécial ne contenant que cette valeur. Il n'y a pas d'autre fonction pour convertir explicitement une valeur dans un autre type.

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 tonumber() 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 true (vraie).

nil

« Nil » est le type de donnée pour nil, qui existe pour représenter l'absence d'une valeur, mais pas l'inexistence d'une variable décrétée par défaut de visibilité globale.

« 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 (item jamais assigné de table) et une variable-clé chargée avec la valeur nil.

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

Booléen

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

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. Et contrairement à d'autres langages, seuls false et nil sont "false" à la conversion, le nombre 0 et la chaine vide (affectée par un ="" ou bien ='') sont tous 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 au besoin 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 :

  • \a (bell, caractère d'appel, 7)
  • \b (backspace, espacement arrière, 8)
  • \t (horizontal tab, tabulation horizontale, 9)
  • \n (newline, saut de ligne, 10)
  • \v (vertical tab, tabulation verticale, 11)
  • \f (form feed, saut de page, 12)
  • \r (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 mis juste après le crochet long ouvrant, dans ce cas ce retour à la ligne n'est pas intégré à la chaine mais mis juste après la chaine (avant son crochet long fermant). Chaque saut de ligne, quel que soit son codage, est interprété comme un seul caractère '\n' (newline, saut de ligne).

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

-- est équivalente à celle-ci
foo = 'bar\\tbaz\n'

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 : 123456.78). Les nombres peuvent aussi utiliser la notation en exposant sans espace (exemples : 1.23e-10, 123.45e20, ou 1.23E5). Les entiers peuvent aussi être donnés en notation hexadécimale en utilisant le préfix 0x (exemple : 0x3A).

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 math.huge représente l'infini positif de même que la division par zéro 1/0, et 0/0 permet de représenter efficacement NaN.

Notez que tous les nombres sont considérés comme vrais lorsqu'ils sont convertis en booléen. Ceci est différent de la plupart des autres langues, où le nombre 0 est généralement considéré comme faux. Lorsqu'ils sont convertis en une chaîne, les nombres finis sont représentés en décimal, éventuellement en notation E; NaN est "nan" or "-nan"; and infinities are "inf" or "-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 :

  • [expression1] = expression2 utilise la (première) valeur de expression1 comme la clé et la (première) valeur de expression2 comme valeur ;
  • nom = expression est équivalent à ["nom"] = expression ;
  • expression est à peu près équivalent à [i] = expression, 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 table['clé']. Si on écrit table[clef], c'est un accès en référence à la variable de nom: clef. Le retour de fonction d'accès pour un élément simple de table dont la clé est clef est alors une chaine vide (il ne s'agit pas d'une chaine non affectée type nil rendu par la fonction d'accès si la variable n'est pas définie ni localement ni globalement). 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 table.clef. Cela est équivalent à table['clef'].
Pour appeler une fonction contenue dans une table, on peut utiliser le deux-points, par exemple : table:func( ... ). Cette notation est équivalente à table['func']( table, ... ).

Une séquence est une table avec des valeurs définies (valeurs différentes de 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. Elles ignorent les clés négatives et ignorent celles placées après une valeur nil (un trou).

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 :

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

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

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

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

Quand une table est convertie en chaine, le résultat est "table". Ceci peut être modifié en changeant la méta-méthode __tostring. Même la table vide est considérée comme true en tant que booléen. N.B. Pour convertir une chaîne en table voir dans la Bibliothèque text la fonction mw.text.split(...)

Fonction

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

Les fonctions sont créées grâce au mot-clé function et appelées en utilisant les parenthèses. 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" a pour résultat une "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 hébergé où le code non natif n'est pas autorisé.

Le type thread permet de gérer les co-routines, il n'est pas disponible dans le bac à sable de 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
C'est utilisé quand l'accès t[clef] aurait retourné nil. Si la valeur de ce champ est une table, l'accès sera tenté de nouveau dans cette table (par exemple __index[key], ce qui pourra a son tour appeler la méta-table de cette table). Si la valeur de ce champ est une fonction, celle-ci est appelée ainsi : __index( t, key ). La fonction rawget() court-circuite cette méta-méthode.
__newindex
C'est utilisé lorsqu'une valeur est assignée à une clé de la table et qu'il n'y a pas de valeur pour cette clé (t[key] = value avec rawget( t, key ) retournerait nil). Si la valeur de ce champ est une table, l'affectation sera répétée dans cette table (__newindex[key] = value). Si la valeur de ce champ est une fonction celle-ci est appelée comme suit : __newindex( t, key, value ). 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, t( ··· ). Cette valeur doit être une fonction, qui est appelée à la manière de : __call( t, ··· ).
__mode
C'est 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 » ses 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 indéterminé en cas de modification de ce champ dans une table méta-table.

Les autres champs de méta-tables sont :

Pour les opérateurs binaires, Lua regarde d'abord la méta-table du paramètre de gauche (s'il y en a une), puis celle du paramètre de droite quand il cherche quelle méta-méthode utiliser.
Pour les opérateurs relationnels, la méta-méthode est utilisée uniquement si la même fonction est donnée pour les deux paramètres dans leurs méta-tables respectives. Des fonctions anonymes, même avec un contenu identique et la même fermeture, peuvent n'être 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 que "string" n'est pas disponible, seule une copie est disponible dans les modules.

Variables

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

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

Les variables globales sont stockées dans une table Lua appelée environment. Cette table est généralement disponible en tant que variable globale _G. Il est possible d'attacher une méta-table à cette table globale. Les méta-méthodes __index et __newindex seront 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 #getfenvgetfenv() 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 section Déclaration locale de variables).

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 table 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érateur Fonction Exemple Méta-méthode associée Notes
+ Addition a + b __add
- Soustraction a - b __sub
* Multiplication a * b __mul
/ Division a / b __div La division par zéro n'est pas une erreur : si a est non nul, a/0 retournera une valeur infinie (voir math.huge) ou NaN (selon l'implémentation interne de la bibliothèque mathématique et sa représentation des nombres), sinon 0/0 retournera une valeur NaN.
% Modulo a % b __mod L'opération est définie comme a % b == a - math.floor( a / b ) * b

Le diviseur et le dividende peuvent ne pas être entiers : le résultat est le reste (non nécessairement entier) d'une division dont le quotient est minoré par un entier ; ce reste (dont la valeur absolue est strictement inférieure à celle du diviseur) est alors de même signe que ce diviseur (ou nul si le dividende est un multiple du diviseur) :

si b est nul, l'opération ne retourne pas d'erreur mais retourne NaN ; sinon elle retourne une valeur positive dans [0, b[ si b est positif (cas habituel), ou négative dans ]b, 0] si b est négatif (ce comportement est différent de l'opérateur % limité aux entiers et utilisé en C, C++, Java, etc.).

^ Exposant a ^ b __pow Les valeurs non entières de l'exposant b sont autorisées ; mais dans ce cas la base a doit être positive ou nulle, sinon le résultat indéfini sera retournée comme une valeur NaN (en effet l'opération ne peut représenter aucune des multiples racines complexes possibles).
- Négation -a __unm

Opérateurs relationnels

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

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

La différence (ou inégalité) (~=) est 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 :

  • a < b utilise __lt( a, b ) (si a et b sont des tables, leur méta-méthode __lt doit référencer la même fonction, sinon elle ne sera pas utilisée).
  • a <= b utilise __le( a, b ) si disponible, ou si __lt est disponible alors not _lt( b, a ) est utilisé (qui ne retournera que false ou true et donc permet de définir une relation d'ordre total).
  • a > b 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 and, or, et not. Tous considèrent nil et false comme faux et toutes les autres valeurs comme vraies.

Pour and, 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 or, 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 not, le résultat est toujours true ou false.

Notez que and et or 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 (a .. b). 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 __concat 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 a = a .. b 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 : #a. Si a 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 a est une table qui n'est pas une séquence, #a peut retourner n'importe quelle valeur N telle que a[N] est différent de nil et a[N+1] vaut nil, même si il y a d'autres valeurs non-nil à des index plus élevés. Par exemple :

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

-- ceci peut retourner 2 ou 4
-- et ceci peut changer même si la table n'est pas modifiée
mw.log( #a )

Préséance des opérateurs

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

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

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

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

Appels de fonctions

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

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 (func()()). Si une expression plus complexe qu'un accès de variable est nécessaire pour déterminer quelle fonction doit être appelée, une expression entre parenthèses pourra être utilisée.

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

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

-- Ceci retourne une fonction qui ajoute un nombre à son paramètre
function makeAdder( n )
    return function( x )
        -- The variable n from the outer scope is available here to be added to x
        return x + n
    end
end

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

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 :

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

join( ', ', 'foo', 'bar', 'baz' )
-- retourne la chaine "foo, bar, baz"

La fonction select() sert à traiter les expressions vararg. En particulier select( '#', ... ) doit être utilisée au lieu de #{ ... } pour compter le nombre de valeurs dans l'expression vararg car { ... } n'est pas forcément une 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 : do block end. Ceci peut être utilisé pour limiter la portée de variables locales ou pour ajouter un return ou un break au milieu d'un autre bloc.

Affectations

variable-list = expression-list

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 a, b = b, a va effectivement échanger les valeurs contenues dans a et b.

Déclaration locale de variables

local variable-list

local variable-list = expression-list

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 local x = x 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

while exp do block end

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

repeat block until exp

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.

for name = exp1, exp2, exp3 do block end
for name = exp1, exp2 do block end

La première forme de boucle for déclare une variable locale et répète le bloc pour des valeurs de cette variable allant de 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.

for var-list in expression-list do block end

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'' is the first variable in ''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.

if exp1 then block1 elseif exp2 then block2 else block3 end

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

return expression-list

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 getfenv() ou debug.traceback().

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

break

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

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

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 :

-- Basic declaration
function func( var-list ) block end
func = function ( var-list ) block end
-- Local function
local function func( var-list ) block end
local func; func = function ( var-list ) block end
-- Function as a field in a table
function table.func( var-list ) block end
table.func = function ( var-list ) block end
-- Function as a method in a table
function table:func( var-list ) block end
table.func = function ( self, var-list ) block end

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.

Fonctions de base

_G

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

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

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

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

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

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

_VERSION

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

assert

assert( v, message, ... )

Si v est nil ou false, la fonction génère une erreur. Dans ce cas, message 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 v a toute autre valeur, assert retourne tous les paramètres y compris v et message.

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

-- This doesn't check for errors
local result1, result2, etc = func( ... )

-- This works the same, but does check for errors
local result1, result2, etc = assert( func( ... ) )

error

error( message, level )

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

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

getfenv

getfenv( f )

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

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

  • si 1, nil ou absent, retourne l'environnement de la fonction qui appelle getfenv. 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 getfenv retournera nil systématiquement.

getmetatable

getmetatable( table )

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

ipairs

ipairs( t )

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

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

next

next( table, clef )

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

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

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

pairs

pairs( t )

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

for k, v in pairs( t ) do
    -- process each key-value pair
end

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

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

pcall

pcall( f, ... )

Appelle la fonction f avec les paramètres indiqués en « mode protégé ». Ceci signifie que si une erreur se produit durant l'appel à f, pcall 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 :

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

rawequal

rawequal( a, b )

Ceci est équivalent à a == b mis à part qu'une éventuelle méta-méthode __eq sera ignorée.

rawget

rawget( table, clef )

Ceci est équivalent à table[clef] mis à part qu'une éventuelle méta-méthode __index sera ignorée.

rawset

rawset( table, clef, valeur )

Ceci est équivalent à table[clef] = valeur mis à part qu'une éventuelle méta-méthode __newindex sera ignorée.

select

select( index, ... )

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

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

setmetatable

setmetatable( table, metatable )

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 __metatable, setmetatable génère une erreur.

tonumber

tonumber( valeur, base )

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 au dessus de 10, la lettre 'A' (majuscule ou minuscule) représente 10, 'B' représente 11, 'F' représente l'hexadécimal base 16 (utilisé pour les codes couleurs RVB) 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 6.022e23). 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

tostring( valeur )

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 __tostring. Si cette méta-méthode existe, l'appel à tostring retournera la seule valeur retournée par __tostring( value ) à la place.

type

type( valeur )

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

unpack

unpack( table, i, j )

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

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

xpcall

xpcall( f, errhandler )

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

La fonction xpcall pourrait ressembler à quelque chose comme suit :

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

Bibliothèque de débogage

debug.traceback

debug.traceback( message, level )

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

Bibliothèque mathématique

math.abs

math.abs( x )

Retourne la valeur absolue de x.

math.acos

math.acos( x )

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

math.asin

math.asin( x )

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

math.atan

math.atan( x )

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

math.atan2

math.atan2( y, x )

Retourne l'arc tangente de y/x (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

math.ceil( x )

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

math.cos

math.cos( x )

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

math.cosh

math.cosh( x )

Retourne le cosinus hyperbolique de x.

math.deg

math.deg( x )

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

math.exp

math.exp( x )

Retourne la valeur .

math.floor

math.floor( x )

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

math.fmod

math.fmod( x, y )

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

math.frexp

math.frexp( x )

Retourne m et e tels que :

  • si x est fini et différent de zéro : , e est un entier et la valeur absolue de m est dans l'intervalle  ;
  • 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

math.ldexp( m, e )

Retourne (e doit être un entier).

math.log

math.log( x )

Retourne le logarithme naturel de x.

math.log10

math.log10( x )

Retourne le logarithme en base 10 de x.

math.max

math.max( x, ... )

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

math.min( x, ... )

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

math.modf( x )

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

math.pi

La valeur de .

math.pow

math.pow( x, y )

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

math.rad

math.rad( x )

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

math.random

math.random( m, n )

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
  • Avec un paramètre, retourne un entier dans l'intervalle
  • Avec deux paramètres, retourne un entier dans l'intervalle

math.randomseed

math.randomseed( x )

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

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

math.sin

math.sin( x )

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

math.sinh

math.sinh( x )

Retourne le sinus hyperbolique de x.

math.sqrt

math.sqrt( x )

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

math.tan

math.tan( x )

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

math.tanh

math.tanh( x )

Retourne la tangente hyperbolique de x.

Bibliothèque du système d'exploitation

os.clock

os.clock()

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

os.date

os.date( format, time )

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, %c est utilisé.

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

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

  • year (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 *t, alors la date est retournée en tant que chaine, formatée en accord avec les règles de la fonction C strftime.

os.difftime

os.difftime( t2, t1 )

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

os.time

os.time( table )

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.

Bibliothèque Package

require

require( nomDeModule )

Charge le module indiqué.

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

Sinon appelle chaque chargeur (loader) dans package.loaders 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 package.loaded[modulename] et est ensuite retournée.

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

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

local p = {}

p.someDataValue = 'Hello!'

return p

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

local giving = require( "Module:Giving" )

local value = giving.someDataValue -- value is now 'Hello!'

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 package.preload[modulename] 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

package.seeall( table )

Fixe la méta-méthode __index pour table à _G.

Bibliothèque de manipulation de chaines

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

Attention : La bibliothèque string suppose 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

string.byte( s, i, j )

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

string.char

string.char( ... )

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

local value = string.char( 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21 ) -- value is now 'Hello!'

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

string.find

string.find( s, motif, init, normal )

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 find retourne nil. Si le motif a des « captures », alors si une correspondance est trouvée le résultat 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 normal 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 normal est fourni, alors init doit l'être aussi (la valeur peut être nil).

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

string.format

string.format( formatstring, ... )

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

La chaine de format formatstring suit les mêmes règles que les fonctions de la famille printf en C standard.

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

L'option de conversion q est similaire à s mais formate la chaine de façon à ce qu'elle soit utilisable par l'interpréteur Lua de façon correcte: la chaine est écrite entre guillemets, et les guillemets, retours à la ligne, codes zéro ("\0") et les barres obliques inversées ("\") présents dans le paramètre formatstring sont traités comme du contenu.

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

Identique à mw.ustring.format().

string.gmatch

string.gmatch( s, motif )

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

string.gsub( s, motif, rempl, n )

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

Si 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 %n, 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 %0 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

string.len( s )

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 à #s.

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

string.lower

string.lower( s )

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

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

string.match

string.match( s, motif, init )

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

string.rep( s, n )

Retourne une chaine qui est la concaténation de n copies de la chaine s. Identique à mw.ustring.rep().

string.reverse

string.reverse( s )

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

string.sub( s, i, j )

Retourne une sous-chaine de s qui débute à la position i et continue jusqu'à la position j, i et j pouvant être négatifs. Si j est absent il est considéré comme valant -1 (qui signifie la longueur de la chaine).

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

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

string.upper

string.upper( s )

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

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

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 {n,m} avec PCRE) ;
  • Les seuls caractères de contrôle qui n’ont aucune profondeur sont ^, $ et %f[set], le motif de « frontière » (Lua n’offre pas la possibilité d’utiliser \b 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 », "\000"). Utilisez %z à la place.

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

Classes de caractères

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

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

  • x : (où x n’est aucun des caractères « magiques » ^$()%.[]*+-?) représente le caractère x lui-même.
  • . : (le point de ponctuation) représente un caractère quelconque (\000-\255), y compris un saut de ligne, ou un caractère de contrôle ou un octet non ASCII.
  • %a : représente les lettres ASCII (a-zA-Z, sans les lettres accentuées).
  • %c : représente les caractères de contrôle ASCII (\000-\031\127), y compris les tabulations et sauts de ligne.
  • %d : représente les chiffres latins (0-9).
  • %l : représente les lettres ASCII minuscules.
  • %p : représente les signes de ponctuation et les symboles du jeu de caractères ASCII (!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~).
  • %s : représente les caractères d’espacement ASCII (l’espace et les contrôles de tabulation ou de saut de ligne).
  • %u : représente les lettres ASCII majuscules.
  • %w : représente les caractères alphanumériques ASCII (0-9a-zA-Z).
  • %x : représente les chiffres hexadécimaux (0-9A-Fa-f).
  • %z : représente le caractère NULL \000 (le caractère de contrôle dont la valeur numérique est nulle).
  • %A : tous les caractères (octets) qui ne sont pas dans %a.
  • %C : tous les caractères (octets) qui ne sont pas dans %c.
  • %D : tous les caractères (octets) qui ne sont pas dans %d.
  • %L : tous les caractères (octets) qui ne sont pas dans %l.
  • %P : tous les caractères (octets) qui ne sont pas dans %p.
  • %S : tous les caractères (octets) qui ne sont pas dans code>%s.
  • %U : tous les caractères (octets) qui ne sont pas dans %u.
  • %W : tous les caractères (octets) qui ne sont pas dans %w.
  • %X : tous les caractères (octets) qui ne sont pas dans %x.
  • %Z : tous les caractères (octets) qui ne sont pas dans %z.
  • %x : (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.
  • [set] : représente l'ensemble des caractères présents dans l’union des caractères et des classes prédéfinies présentes 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 [0-7] représente les chiffres du système octal, et [0-7%l%-] représente les chiffres du système octal plus les lettres ASCII minuscules plus le caractère '-'.
  • [^set]: 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 :

  • 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 ;
  • %n, pour n compris entre 1 et 9. Cet élément correspond à une sous-chaine valant la n-ième chaine capturée (voir plus bas) ;
  • %bxy, ou x et y sont deux caractères distincts. Cet élément correspond à la chaine qui commence par x, se termine par y, et où x et y sont équilibrés (balanced). Cela signifie, en lisant la chaine de gauche à droite, compter +1 pour chaque x et -1 pour chaque y, le y terminal est le premier y pour lequel le compte atteint 0. Par exemple, l'élément %b() correspond à une expression avec des parenthèses équilibrées.
  • %f[set], un motif de frontière ; 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 \000.


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.

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 chaine 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 '(a*(.)%w(%s*))', la partie de la chaine qui concorde avec 'a*(.)%w(%s*)' 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 '%s*' a le numéro 3.

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

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

Bibliothèque table

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

Les fonctions table.foreach(), table.foreachi(), et table.getn() sont encore disponibles, mais utilisez plutôt pairs(), ipairs(), et l'opérateur de longueur # à la place.

table.concat

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

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

La valeur par défaut de sep est 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

table.insert( table, valeur )
table.insert( table, pos, valeur )

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

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

table.maxn

table.maxn( table )

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

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

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

table.remove

table.remove( table, pos )

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

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

table.sort

table.sort( table, comp )

Trie les éléments de la table dans l'ordre indiqué, sur place, de table[ 1 ] à table[ #table ]. 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 not comp( a[ i + 1 ], a[ i ] ) 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.

Fonctions de base

mw.addWarning

mw.addWarning( text )

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

mw.allToString

mw.allToString( ... )

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

mw.clone

mw.clone( valeur )

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

mw.getCurrentFrame

mw.getCurrentFrame()

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

mw.incrementExpensiveFunctionCount

mw.incrementExpensiveFunctionCount()

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

mw.isSubsting

mw.isSubsting()

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

mw.loadData

mw.loadData( module )

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

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

  • le module n'est évalué qu'une fois par page, plutôt qu'une fois par appel à {{#invoke:}} ;
  • le module n'est pas enregistré dans package.loaded ;
  • la valeur retournée par le module chargé doit être une table. Les autres types ne sont pas gérés ;
  • la table retournée (et ses sous-tables) peut contenir des booléens, des nombres, des chaines et d'autres tables. Les autres types, en particulier les fonctions, ne sont pas autorisés ;
  • la table retournée (et toutes ses sous-tables) ne doit avoir de méta-tables ;
  • toutes les clés de la table doivent être des booléens, des nombres ou des chaines ;
  • la table réellement retournée par mw.loadData() a des méta-méthodes qui fournissent un accès en lecture seule à cette table. Dans la mesure où elle ne contient pas directement les données, pairs() et ipairs() fonctionnent mais les autres méthodes, y compris #table, next(), et les fonctions de la bibliothèque table, ne fonctionneront pas correctement.

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

mw.dumpObject

mw.dumpObject( objet )

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

mw.log

mw.log( ... )

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

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

mw.logObject

mw.logObject( objet )
mw.logObject( objet, prefix )

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

L'objet Frame

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

frame.args

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

{{#invoke:module|fonction|arg1|arg2|clef = arg3}}

alors frame.args[1] retournera "arg1", frame.args[2] retournera "arg2", et frame.args['clef'] (ou frame.args.name) retournera "arg3". Il est également possible d'itérer sur les paramètres en utilisant pairs( frame.args ) ou ipairs( frame.args ). However, due to how Lua implements table iterators, iterating over arguments will return them in an unspecified order, and there's no way to know the original order as they appear in wikitext.

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

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

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

Si des paramètres contenant des appels de modèles ou des paramètres à triple accolades sont utilisés comme paramètres au sein de l' #invoke, ils seront évalués sur une seule profondeur avant d'être envoyés à Lua (les triple accolades incluant d'autres triple accolades ne sont pas substituées. On peut utiliser des appels à Lua en imbrication ou bien un modèle appelant le modèle appelant le module). Si certains tags utilisant la notation XML sont présents (comme <pre>, <nowiki>, <gallery> ou <ref>) ils sont convertis en « strip markers », des chaines spéciales commençant avec le caractère DELETE (ASCII 127), pour être remis en tant que résultat avec le code HTML correspondant lors de leur retour du #invoke.

frame:callParserFunction

frame:callParserFunction( nom, args )
frame:callParserFunction( nom, ... )
frame:callParserFunction{ name = chaine, args = table }

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

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

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

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

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

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

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

frame:expandTemplate

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

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

Applique une transclusion. L'appel :

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

fait à peu près la même chose en Lua que {{template|arg1|arg2|name=arg3}} en wikitexte. Comme pour la transclusion, si titre ne contient pas de précision d'espace de noms, la fonction cherche dans l'espace de noms « Modèle: ».

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

-- ceci est à peu près équivalent au wikitexte {{template|{{!}}}}
frame:expandTemplate{ title = 'template', args = { '|' } }

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

frame:extensionTag

frame:extensionTag( nom, contenu, args )
frame:extensionTag{ name = chaine, content = chaine, args = table_ou_chaine }

Ceci est équivalent à frame:callParserFunction() avec '#tag:' .. nom comme nom de fonction et avec contenu avant les paramètres args.

-- Ces expressions sont équivalentes
frame:extensionTag{ name = 'ref', content = 'some text', args = { name = 'foo', group = 'bar' } }
frame:extensionTag( 'ref', 'some text', { name = 'foo', group = 'bar' } )

frame:callParserFunction{ name = '#tag:ref', args = {
    'some text', name = 'foo', group = 'bar'
} }

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

frame:getParent

frame:getParent()

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

Par exemple, si le modèle {{Exemple}} contient le code {{#invoke:ModuleExemple}}, et une page utilise ce modèle avec des paramètres ({{Exemple|arg1|arg2}}), appeler mw.getCurrentFrame():getParent().args[1], mw.getCurrentFrame():getParent().args[2] dans « Module:ModuleExemple » renverra "arg1", "arg2".

frame:getTitle

frame:getTitle()

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

frame:newChild

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

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

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

Ceci sert principalement pour la console de debug afin de tester les fonctions qui sont normalement appelées par {{#invoke:}}. Le nombre de frames qui peuvent être créés est limité.

frame:preprocess

frame:preprocess( chaine )
frame:preprocess{ text = chaine }

Traite le wikitexte indiqué dans le contexte de l'objet frame. Ainsi les modèles, parser-functions et paramètres tels que {{{1}}} sont évalués et remplacés par leurs résultats. Certains tags en notation XML (tels que <pre>, <nowiki>, <gallery> ou <ref>) seront convertis en « strip markers », des chaines spéciales commençant avec le caractère DELETE (ASCII 127), pour être replacés avec le code HTML correspondant lors de leur retour en tant que résultat du #invoke.

Si vous souhaitez traiter uniquement un modèle, utilisez plutôt frame:expandTemplate. Ce dernier est plus rapide et moins sujet aux erreurs si les paramètres contiennent le caractère « | » ou d'autres éléments ayant un sens spécial.

If you are expanding a single parser function, use frame:callParserFunction for the same reasons.

frame:getArgument

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

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

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

frame:newParserValue

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

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

frame:newTemplateParserValue

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

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

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

frame:argumentPairs

frame:argumentPairs()

Identique à pairs( frame.args ). Existe pour compatibilité avec des versions précédentes de Scribunto.

Bibliothèque de hachage

mw.hash.hashValue

mw.hash.hashValue( algo, chaine )

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

mw.hash.listAlgorithms

mw.hash.listAlgorithms()

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

Bibliothèque html

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

Les fonctions documentées comme mw.html.nom sont disponible dans la table globale mw.html. Les fonction documentées comme mw.html:nom sont des méthodes de l'objet créé par mw.html.create.

Un exemple de base pourrait ressembler à ceci :

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

mw.html.create

mw.html.create( balise, args )

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

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

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

mw.html:node

html:node( html )

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

mw.html:wikitext

html:wikitext( ... )

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

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

mw.html:newline

html:newline()

Ajoute une nouvelle ligne à l'objet mw.html.

mw.html:tag

html:tag( balise, args )

Ajoute un nouveau nœud enfant balise, et renvoie un objet mw.html représentant le nouveau nœud. Le paramètre args est identique à celui de mw.html.create.

mw.html:attr

html:attr( nom, valeur )
html:attr( table )

Définie un attribut HTML {{{1}}} sur le nœud. Alternativement, une table contenant le couple d'attribut {{{1}}} peut être passée. Avec la première forme, une valeur nulle désactive l'attribut nom si cet attribut avait une valeur précédente.

mw.html:getAttr

html:getAttr( nom )

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

mw.html:addClass

html:addClass( classe )

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

mw.html:css

html:css( nom, valeur )
html:css( table )

Définie une propriété CSS nom avec comme valeur valeur sur le nœud. Alternativement, une table contenant le couple de propriété {{{1}}} peut être passée. Avec la première forme, une valeur nulle désactive la propriété nom si cette propriété avait une valeur précédente.

mw.html:cssText

html:cssText( css )

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

mw.html:done

html:done()

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

mw.html:allDone

html:allDone()

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

Bibliothèque language

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

Les fonctions documentées comme mw.language.name sont disponibles dans la table globale mw.language. Les fonctions documentées comme mw.language:name sont des méthodes d'un objet Language (voir mw.language.new).

mw.language.fetchLanguageName

mw.language.fetchLanguageName( code, enLangue )

Le nom complet de la langue du code indiqué : par défaut dans la langue du wiki (autonyme), ou traduit dans la langue indiquée dans enLangue.

mw.language.fetchLanguageNames

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

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

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

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

mw.language.getContentLanguage

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

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

mw.language.getFallbacksFor

mw.language.getFallbacksFor( code )

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

mw.language.isKnownLanguageTag

mw.language.isKnownLanguageTag( code )

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

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

mw.language.isSupportedLanguage

mw.language.isSupportedLanguage( code )

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

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

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

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

mw.language.isValidBuiltInCode

mw.language.isValidBuiltInCode( code )

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

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

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

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

mw.language.isValidCode

mw.language.isValidCode( code )

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

Le code peut ne correspondre à aucune langue connue.

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

mw.language.new

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

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

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

mw.language:getCode

lang:getCode()

Retourne le code de langue correspondant à cet objet.

mw.language:getFallbackLanguages

lang:getFallbackLanguages()

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

mw.language:isRTL

lang:isRTL()

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

mw.language:lc

lang:lc( chaine )

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

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

mw.language:lcfirst

lang:lcfirst( chaine )

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

mw.language:uc

lang:uc( chaine )

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

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

mw.language:ucfirst

lang:ucfirst( chaine )

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

mw.language:caseFold

lang:caseFold( chaine )

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

mw.language:formatNum

lang:formatNum( nombre )
lang:formatNum( nombre, options )

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

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

  • noCommafy: true pour omettre les séparateurs de milliers.

Digit transformation may still occur, which may include transforming the decimal separator.

mw.language:formatDate

lang:formatDate( format, timestamp, local )

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

La chaine de formatage et les valeurs supportées pour timestamp sont identiques à celles de la fonction parseur #time. Notez que les antislash ("\") peuvent nécessiter d'être doublés en Lua alors que ce n'est pas nécessaire en wikitexte (car ce caractère a un sens particulier en Lua et non en wikitexte) :

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

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

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

mw.language:formatDuration

lang:formatDuration( secondes )
lang:formatDuration( secondes, intervallesPossible )

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

intervallesPossible, si indiqué, est une table avec des valeurs nommant les unités d'intervalle à utiliser dans la réponse. Cela comprend : 'millennia', 'centuries', 'decades', 'years', 'weeks', 'days', 'hours', 'minutes', et 'seconds'.

mw.language:parseFormattedNumber

lang:parseFormattedNumber( chaine )

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

mw.language:convertPlural

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

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

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

mw.language:convertGrammar

lang:convertGrammar( mot, declinaison )
lang:grammar( declinaison, mot )

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

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

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

mw.language:gender

lang:gender( genre, masculin, feminin, neutre )
lang:gender( genre, { masculin, feminin, neutre } )

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

mw.language:getArrow

lang:getArrow( direction )

Retourne un caractère Unicode correspondant direction :

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

mw.language:getDir

lang:getDir()

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

mw.language:getDirMark

lang:getDirMark( opposite )

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

mw.language:getDirMarkEntity

lang:getDirMarkEntity( opposite )

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

mw.language:getDurationIntervals

lang:getDurationIntervals( secondes )
lang:getDurationIntervals( secondes, unites )

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

unites, si précisé, est une table avec comme valeurs les noms des unités à utiliser : 'millennia', 'centuries', 'decades', 'years', 'days', 'hours', 'minutes', et 'seconds'.

Bibliothèque message

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

Les fonctions documentées comme mw.message.name sont disponbiles dans la table globale mw.message. Les fonctions documentées comme mw.message:name sont des méthodes des objets Message (voir mw.message.new).

mw.message.new

mw.message.new( clef, ... )

Crée un nouvel objet message pour le message clef.

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

mw.message.newFallbackSequence

mw.message.newFallbackSequence( ... )

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

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

mw.message.newRawMessage

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

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

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

mw.message.rawParam

mw.message.rawParam( valeur )

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

mw.message.numParam

mw.message.numParam( valeur )

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

mw.message.getDefaultLanguage

mw.message.getDefaultLanguage()

Retourne un objet Language pour la langue courante.

mw.message:params

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

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

Retourne l'objet msg pour autoriser des appels chainés.

mw.message:rawParams

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

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

Retourne l'objet msg pour autoriser des appels chainés.

mw.message:numParams

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

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

Retourne l'objet msg pour autoriser des appels chainés.

mw.message:inLanguage

msg:inLanguage( langue )

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

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

Retourne l'objet msg pour autoriser des appels chainés.

mw.message:useDatabase

msg:useDatabase( bool )

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

La valeur par défaut est true.

Retourne l'objet msg pour autoriser des appels chainés.

mw.message:plain

msg:plain()

Remplace les paramètres et retourne le message tel quel en wikitexte. Les appels à des modèles et à des fonctions parseurs sont laissés intacts.

mw.message:exists

msg:exists()

Retourne un booléen indiquant si la clé de message existe.

mw.message:isBlank

msg:isBlank()

Retourne un booléen indiquant si la clé de message correspond à un contenu. Retourne true si la clé n'existe pas ou si le message est la chaine vide.

mw.message:isDisabled

msg:isDisabled()

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

Bibliothèque site

mw.site.currentVersion

Une chaine contenant la version actuelle de MediaWiki.

mw.site.scriptPath

La valeur de $wgScriptPath.

mw.site.server

La valeur de $wgServer

mw.site.siteName

La valeur de $wgSitename

mw.site.stylePath

La valeur de $wgStylePath

mw.site.namespaces

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

Les données disponibles sont :

  • id : numéro de l'espace de noms ;
  • name : nom local de l'espace de noms ;
  • canonicalName : nom générique de l'espace de noms ;
  • displayName : pour l'espace de noms 0 : le nom à utiliser pour affichage, car name vaut la chaine vide sur la plupart des wikis ;
  • hasSubpages : est-ce que les sous-pages sont actives pour cet espace de noms ;
  • hasGenderDistinction : est-ce que l'espace de noms a des alias différents selon le genre ;
  • isCapitalized : est-ce que la première lettre des pages de cet espace de noms doit être mise en majuscule ;
  • isContent : est-ce un espace de noms pour du contenu ;
  • isIncludable : est-ce que les pages de cet espace de noms peuvent être transclues ;
  • isMovable : est-ce que les pages de cet espace de noms peuvent être déplacées ;
  • isSubject : est-ce que c'est un espace de noms de sujet (subject namespace) ;
  • isTalk : est un espace de noms de discussion ;
  • defaultContentModel : le type de contenu par défaut pour l'espace de noms, sous forme de chaine (voir Manual:ContentHandler) ;
  • aliases : liste des alias pour cet espace de noms ;
  • subject : référence vers l'espace de noms sujet de cet espace de noms ;
  • talk : référence vers l'espace de noms de discussion de cet espace de noms ;
  • associated : référence à l'espace de noms associé (Discussion MediaWiki pour MediaWiki par exemple, et vice-versa).

Une méta-table est présente pour permettre de chercher un espace de noms par son nom (localisé ou générique). Par exemple mw.site.namespaces[4] et mw.site.namespaces.Project retourneront la même chose.

mw.site.contentNamespaces

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

mw.site.subjectNamespaces

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

mw.site.talkNamespaces

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

mw.site.stats

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

  • pages: nombre de pages dans le wiki ;
  • articles: nombre d'articles dans le wiki ;
  • files: nombre de fichiers dans le wiki ;
  • edits: nombre d'éditions dans le wiki ;
  • views: nombre de visualisation dans le wiki. Non disponible si $DisableCounters est présent ;
  • users: nombre d'utilisateurs dans le wiki ;
  • activeUsers: nombre d'utilisateurs actifs dans le wiki ;
  • admins: nombre d'utilisateurs dans le groupe 'sysop' dans le wiki.

mw.site.stats.pagesInCategory

mw.site.stats.pagesInCategory( categorie, type )

Cette fonction est couteuse

Retourne des statistiques sur la catégorie. Si type est non précisé, vaut nil, ou '*', cette fonction retourne une table avec les éléments suivants :

  • all : total des éléments ci-dessous ;
  • subcats : nombre de sous-catégories ;
  • files : nombre de fichiers ;
  • pages : nombre de pages.

Si type est l'une des clés ci-dessus seule la valeur correspondante est retournée, sous forme de nombre.

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

mw.site.stats.pagesInNamespace

mw.site.stats.pagesInNamespace( ns )

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

mw.site.stats.usersInGroup

mw.site.stats.usersInGroup( groupe )

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

mw.site.interwikiMap

mw.site.interwikiMap( filtre )

Retourne une table contenant les préfixes interwiki disponible. Le contenu de la table dépend de la chaine filtre :

  • 'local' uniquement les préfixes des interwiki locaux ;
  • '!local' uniquement les préfixes non locaux ;
  • nil tous les préfixes

Dans ce contexte un préfixe « local » fait référence au même ensemble de projet. Par exemple pour Wikipédia en français, les projets Wikimedia comme Wikipedia en anglais ou Commons sont locaux, tandis que Vikidia, Openstreetmap ou Citizendium sont non locaux.

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

  • prefix - le préfixe interwiki ;
  • url - l'URL vers laquelle l'interwiki pointe. Le nom de la page est représenté par '$1' ;
  • isProtocolRelative - indique si l'URL est protocol-relative ;
  • isLocal - indique si l'URL fait partie du même projet ;
  • isCurrentWiki - indique si l'URL est celle du projet actuel ;
  • isTranscludable - indique si les pages de cet interwiki peuvent être transclue ; ceci nécessite l'activation de ScaryTranscluding ; cette option est désactivée pour les wikis de Wikimedia ;
  • isExtraLanguageLink - indique si l'interwiki est listé dans $wgExtraInterlanguageLinkPrefixes.
  • displayText - texte du lien interlangue pour les interwiki dans $wgExtraInterlanguageLinkPrefixes ; Nil pour les autres ;
  • tooltip - texte de l'infobulle pour les interwiki dans $wgExtraInterlanguageLinkPrefixes ; Nil pour les autres ;

Bibliothèque text

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

mw.text.decode

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

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

Si decodeNamedEntities est absent ou false, les seules entités reconnues sont &lt;, &gt;, &amp;, &quot;, et &nbsp;. Sinon la liste des entitées HTML5 à traiter est chargée depuis la fonction PHP get_html_translation_table.

mw.text.encode

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

Remplace les caractères de la chaine par des entités HTML. Les caractères <, >, &, " et l'espace insécable sont remplacés par l'entité HTML correspondante. Tous les autres sont remplacés par l'entité HTML numérique correspondante.

Si charset est indiqué, il doit contenir une chaine pouvant être utilisée dans une classe de caractères des motifs Ustring, par exemple set dans [set]. Par défaut : '<>&"\' ' (l'espace à la fin est l'espace insécable U+00A0).

mw.text.jsonDecode

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

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

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

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

Limitations :

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

mw.text.jsonEncode

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

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

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

Limitations :

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

mw.text.killMarkers

mw.text.killMarkers( s )

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

mw.text.listToText

mw.text.listToText( liste )
mw.text.listToText( liste, séparateur, conjonction )

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

Le séparateur par défaut est récupéré dans MediaWiki:comma-separator dans la langue locale, et la conjonction par défaut est MediaWiki:and concaténé avec MediaWiki:word-separator.

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

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

mw.text.nowiki

mw.text.nowiki( s )

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

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

mw.text.split

mw.text.split( s, motif, normal )

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

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

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

mw.text.gsplit

mw.text.gsplit( s, motif, normal )

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

mw.text.tag

mw.text.tag( nom, attributs, contenu )
mw.text.tag{ name = nom, attrs = attributs, content = contenu }

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

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

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

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

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

mw.text.trim

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

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

Si charset est indiqué, il doit contenir une chaine syntaxiquement compatible avec les classes de caractères des motifs Ustring, par exemple set dans [set]. Par défaut : les espacement ASCII, '\t\r\n\f '.

mw.text.truncate

mw.text.truncate( texte, longueur )
mw.text.truncate( texte, longueur, suspension )
mw.text.truncate( texte, longueur, suspension, adjusteLongueur )

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

La valeur par défaut pour suspension est prise dans MediaWiki:ellipsis pour le wiki local.

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

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

mw.text.unstripNoWiki

mw.text.unstripNoWiki( s )

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

mw.text.unstrip

mw.text.unstrip( s )

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

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

Bibliothèque title

mw.title.equals

mw.title.equals( a, b )

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

mw.title.compare

mw.title.compare( a, b )

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

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

mw.title.getCurrentTitle

mw.title.getCurrentTitle()

Retourne un objet title pour la page courante.

mw.title.new

mw.title.new( texte, namespace )
mw.title.new( id )

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

Crée un nouvel objet title.

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

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

mw.title.makeTitle

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

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

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

Objet title

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

Notez que les chanps se terminant par « Text » contienne des chaines, tandis que les champs se terminant par « Title » contiennent ou retourne des objet title.

  • id : l'identifiant de la page. Vaut 0 si la page n'existe pas. Cela peut être couteux, et la page sera enregistrée comme lien ;
  • interwiki : le préfixe interwiki ou une chaine vide si aucun ;
  • namespace : le numéro d'espace de noms ;
  • fragment : le fragment, ou vide. Peut être modifié ;
  • nsText : le nom local de l'espace de noms de la page ;
  • subjectNsText : le nom de l'espace de noms sujet de la page ;
  • text : le titre de la page, seul ;
  • prefixedText : le titre de la page, avec espace de noms et interwiki ;
  • fullText : le titre de la page, avec l'espace de nom, l'interwiki et le fragment ;
  • rootText : si c'est une sous-page, le titre de la page de base sans préfixe. Sinon identique à title.text ;
  • baseText : si c'est une sous-page, le titre de la page dont on est la sous-page, sans préfixe. Sinon identique à title.text ;
  • subpageText : si c'est une sous-page, juste le nom de la sous-page. Sinon identique à title.text ;
  • canTalk : indique si la page peut avoir une page de discussion ;
  • exists : indique si la page existe. Alias pour file.exists pour les médias. Pour l'espace de noms Fichiers c’est l'existence de la description du fichier qui est vérifiée, pas celle du fichier lui-même. Cela peut être couteux, et la page sera enregistrée comme lien ;
  • file, fileExists : voir #File metadata ci-dessous ;
  • isContentPage : indique si la page est dans un espace de noms de contenu ;
  • isExternal : indique si la page a un interwiki ;
  • isLocal : indique si la page est locale au projet. Par exemple sur fr.wikipedia.org toutes les Wikipédias sont considérées locales mais pas Vikidia ;
  • isRedirect : indique si la page est une redirection. Cela peut être couteux, et la page sera enregistrée comme lien ;
  • isSpecialPage : indique si la page est dans l'espace de noms "Spécial:" ;
  • isSubpage : indique si la page est une sous-page ;
  • isTalkPage : indique si la page est une page de discussion ;
  • isSubpageOf( title2 ) : indique si la page est une sous-page de title2 ;
  • inNamespace( ns ) : indique si la page est dans l'espace de noms indiqué. ns peut être toute clé trouvée dans mw.site.namespaces ;
  • inNamespaces( ... ) : indique si la page est dans l'un des espaces de nom indiqués. Les espaces de noms peuvent être toute clé trouvée dans mw.site.namespaces ;
  • hasSubjectNamespace( ns ) : indique si l'espace de noms sujet de la page est dans l'espace de noms indiqué. ns peut être toute clé trouvée dans mw.site.namespaces ;
  • contentModel : Le type de contenu pour ce titre, sous forme de chaine. (Voir Manual:ContentHandler.) Cela peut être couteux, et la page sera enregistrée comme lien ;
  • basePageTitle : identique à mw.title.makeTitle( title.namespace, title.baseText ) ;
  • rootPageTitle : identique à mw.title.makeTitle( title.namespace, title.rootText ) ;
  • talkPageTitle : identique à mw.title.makeTitle( mw.site.namespaces[title.namespace].talk.id, title.text ), ou à nil si la page ne peut pas avoir de page de discussion ;
  • subjectPageTitle : identique à mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text ) ;
  • redirectTarget: un objet title correspondant à la cible de la redirection si la page est une redirection que cette page existe ; false dans les autres cas ;
  • protectionLevels : les niveaux de protection de la page. C'est une table dont les clés correspondent à chaque action (« modifier » et « renommer »). Les valeurs de la table sont des tableaux, le premier élément de chacun d'entre eux étant une chaine contenant le niveau de protection. Si la page n'est pas protégée, soit les valeurs de la table, soit les éléments du tableau vaudront nil. Ceci est couteux.
  • subPageTitle( text ) : identique à mw.title.makeTitle( title.namespace, title.text .. '/' .. text ) ;
  • partialUrl() : retourne title.text encodé comme une URL.
  • fullUrl( query, proto ) : Retourne l'URL complète de la page (avec optionnellement un query, une chaine ou une table). proto est optionnel et permet de préciser "http", "https", "relative" (par défaut), ou "canonical" ;
  • localUrl( query ) : retourne l'URL locale de la page (avec optionnellement un query, une chaine ou une table) ;
  • canonicalUrl( query ) : retourne l'URL canonique de la page (avec optionnellement un query, une chaine ou une table) ;
  • getContent() : retourne le contenu non interprété de la page, ou nil si elle n'existe pas (mais pour transclure ses modèles utiliser frame:expandTemplate{ title = ':' .. nom_de_page }). La page sera enregistré comme une transclusion.

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

Since people find the fact surprising, note that accessing any expensive field on a title object records a "link" to the page (as shown on Special:WhatLinksHere, for example). Using the title object's getContent() method or accessing the redirectTarget field records it as a "inclusion", and accessing the title object's file or fileExists fields records it as a "lien vers le fichier".

File metadata

Les objets title représentants des pages dans un espace de nom fichier ou de média auront une propriété appelée file. Ceci est couteux. C'est une table avec la structure suivante :

  • exists : indique si le fichier existe. Sera enregistré comme une utilisation du fichier. La propriété fileExists de l'objet title existe pour des raisons de rétro-compatibilité et est un alias de cette propriété. Si false, toutes les autres propriétés de file seront nil ;
  • width : la largeur du fichier. Si le fichier contient plusieurs pages, c'est la largeur de la première page ;
  • height : la hauteur du fichier. Si le fichier contient plusieurs pages, c'est la hauteur de la première page ;
  • pages : si le format du fichier permet d'avoir plusieurs pages, c'est une table contenant une sous-table pour chaque page du fichier (nil sinon). L'opérateur # peut être utilisé pour connaitre le nombre de page du fichier. Les sous-tables contiennent les propriétés width et height avec la largeur et la hauteur de la page ;
  • size : la taille du fichier en octets ;
  • mimeType : le MIME type du fichier.
Propriétés couteuses

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

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

Bibliothèque uri

mw.uri.encode

mw.uri.encode( s, enctype )

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

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

mw.uri.decode

mw.uri.decode( s, enctype )

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

mw.uri.anchorEncode

mw.uri.anchorEncode( s )

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

mw.uri.buildQueryString

mw.uri.buildQueryString( table )

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

mw.uri.parseQueryString

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

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

Les paramètres numériques optionnels i et j peuvent être utilisé pour que seule la sous-chaine entre i et j soit décodée. Le fonctionnement est identique à celui de string.sub.

mw.uri.canonicalUrl

mw.uri.canonicalUrl( page, query )

Retourne un objet uri pour l'URL canonique de la page, avec une "query" optionnelle (chaine ou table).

mw.uri.fullUrl

mw.uri.fullUrl( page, query )

Retourne un objet uri pour l'URL complète de la page, avec une "query" optionnelle (chaine ou table).

mw.uri.localUrl

mw.uri.localUrl( page, query )

Retourne un objet uri pour l'URL locale de la page, avec une "query" optionnelle (chaine ou table).

mw.uri.new

mw.uri.new( s )

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

mw.uri.validate

mw.uri.validate( table )

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

Objet uri

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

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

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

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

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

Les méthodes de l'objet uri sont :

mw.uri:parse

uri:parse( s )

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

mw.uri:clone

uri:clone()

Crée une copie de l'objet uri.

mw.uri:extend

uri:extend( parametres )

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

Bibliothèque ustring

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

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

mw.ustring.maxPatternLength

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

mw.ustring.maxStringLength

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

mw.ustring.byte

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

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

mw.ustring.byteoffset

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

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

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

mw.ustring.char

mw.ustring.char( ... )

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

local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- value is now 'Привет!'

mw.ustring.codepoint

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

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

mw.ustring.find

mw.ustring.find( s, motif, init, normal )

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

mw.ustring.format

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

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

mw.ustring.gcodepoint

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

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

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

mw.ustring.gmatch

mw.ustring.gmatch( s, motif )

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

mw.ustring.gsub

mw.ustring.gsub( s, motif, rempl, n )

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

mw.ustring.isutf8

mw.ustring.isutf8( s )

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

mw.ustring.len

mw.ustring.len( s )

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

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

mw.ustring.lower

mw.ustring.lower( s )

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

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

mw.ustring.match

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

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

mw.ustring.rep

mw.ustring.rep( s, n )

Identique à string.rep().

mw.ustring.sub

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

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

mw.ustring.toNFC

mw.ustring.toNFC( s )

Convertit la chaine en forme normalisée C. Retourne nil si la chaine n'est pas valide en UTF-8.

mw.ustring.toNFD

mw.ustring.toNFD( s )

Convertit la chaine en forme normalisée D. Retourne nil si la chaine n'est pas valide en UTF-8.

mw.ustring.upper

mw.ustring.upper( s )

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

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

Motifs ustring (pattern)

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

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

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

Bibliothèques chargeables

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

Bibliothèque bit32

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

bit32 = require( 'bit32' )

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

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

bit32.band

bit32.band( ... )

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

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

bit32.bnot

bit32.bnot( x )

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

bit32.bor

bit32.bor( ... )

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

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

bit32.btest

bit32.btest( ... )

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

bit32.bxor

bit32.bxor( ... )

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

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

bit32.extract

bit32.extract( n, field, width )

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

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

bit32.replace

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

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

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

bit32.lshift

bit32.lshift( n, disp )

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

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

bit32.rshift

bit32.rshift( n, disp )

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

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

bit32.arshift

bit32.arshift( n, disp )

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

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

bit32.lrotate

bit32.lrotate( n, disp )

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

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

bit32.rrotate

bit32.rrotate( n, disp )

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

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

Bibliothèque libraryUtil

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

libraryUtil = require( 'libraryUtil' )

libraryUtil.checkType

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

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

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

libraryUtil.checkTypeMulti

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

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

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

libraryUtil.checkTypeForIndex

libraryUtil.checkTypeForIndex( index, value, expectType )

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

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

libraryUtil.checkTypeForNamedArg

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

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

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

libraryUtil.makeCheckSelfFunction

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

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

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

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

luabit

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

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

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

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

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

ustring

La bibliothèque ustring programmé uniquement en Lua peut être chargé avec :

ustring = require( 'ustring' )

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

Bibliothèques d'extension

Les extensions MediaWiki suivantes fournissent des bibliothèques Scribunto additionnelles :

Voir aussi les listes d'extension ScribuntoExternalLibraries et ScribuntoExternalLibraryPaths.

Bibliothèques Scribunto prévues

Ces bibliothèques sont prévues ou sont en attente de validation.

(aucune actuellement)

Différences avec le standard Lua

Fonctions changées

Les fonctions suivantes ont été modifiées :

setfenv()
getfenv()
Peut ne pas être disponible selon la configuration. Si disponible, tenter d'accéder à l'environnement parent échoue.
getmetatable()
Fonctionne sur les tables uniquement, afin d'empêcher l'accès à l'environnement parent.
tostring()
Les adresses des tables et fonctions ne sont pas accessibles, pour limiter l'exploitation d'éventuelles vulnérabilités.
pairs()
ipairs()
Support des méta-méthodes __pairs et __ipairs (ajoutés en Lua 5.2).
pcall()
xpcall()
Certaines erreurs internes ne peuvent pas être interceptées.
require()
Peut gérer certains modules inclus par défaut dans Scribunto ainsi que les modules présents dans l'espace de noms "Module:". Pour accéder aux modules wiki, utiliser le nom de complet de la page, avec l'espace de nom. Ne peut accéder au système de fichier local.

Fonctions et paquetages supprimés

Les paquetages suivants ont été supprimés ou presque. Seules les fonctions listées sont disponibles :

package.*
La gestion des systèmes de fichiers et la bibliothèque C sont supprimées. Les fonctions et tables disponibles sont :
package.loaded
package.preload
package.loaders
Les chargeurs qui accèdent au système de fichier local ou qui chargent des bibliothèque C sont absents. Un chargeur pour les modules dans l'espace "Module:" est ajouté.
package.seeall()
os.*
Certaines de ces fonctions sont non sécurisées (comme os.execute()). Les seules disponibles sont :
os.clock()
os.date()
os.difftime()
os.time()
debug.*
La plupart de ces fonctions sont non sécurisées. Les fonctions disponibles sont :
debug.traceback()

Les fonctions et paquetages suivants ne sont pas disponibles :

collectgarbage()
module()
coroutine.*
Aucun intérêt à être utilisé en Scribunto.
dofile()
loadfile()
io.*, file.*
Permet des accès au système de fichier local, ce qui n'est pas sécurisé.
load()
loadstring()
Enlevé pour permettre une analyse statique du code source Lua. De plus, ceci permettrait d'inclure du code Lua directement dans les articles et les modèles, ce qui n'est pas désiré.
print()
Ceci a été discuté sur wikitech-l et il a été décidé de préférer le retour de valeurs pour améliorer la qualité du code. Si nécessaire, mw.log() peut être utilisé dans la console de débogage.
string.dump()
Peut exposer des données privées de l'environnement parent.

Avertissement supplémentaires

Structures de données référentielles
Les structures de données circulaires et les structures de données où le même nœud peut être atteint par plus d'une voie ne peuvent pas être correctement envoyés à PHP. Tenter de le faire entrainera un comportement indéterminé. Cela inclut (mais n'est pas limité à) la restitution de ces structures de données à partir du module appelé par {{#invoque:}} et passer de telles structures de données en tant que paramètres aux fonctions des bibliothèques Scribunto qui sont mises en œuvre comme des rappels en PHP. En revanche, de telles structures de données peuvent être utilisées librement dans Lua, y compris les valeurs de retour de modules chargés avec mw.loadData().

Écrire des bibliothèques Scribunto

NDT : le traducteur n'ayant pas tout compris aux détails techniques de cette partie, il est possible que certaines traductions soient imprécises. Toute personne ayant une bonne compréhension de cette partie est invitée à relire/corriger. Toute personne utilisant cette partie de la documentation est invitée à valider les éléments avec la version anglaise.

Cette information est utile aux développeurs qui écrivent de nouvelles bibliothèques Scribunto, soit pour inclusion dans Scribunto, soit pour fournir une interface à leurs extensions.

Une bibliothèque Scribunto comporte en général cinq parties :

  • la partie PHP de la bibliothèques ;
  • la partie Lua de la bibliothèque ;
  • la partie PHP des tests ;
  • la partie Lua des tests ;
  • la documentation.

Les bibliothèques existantes sont un bon exemple de code.

Bibliothèques

La partie PHP d'une bibliothèque est une classe qui doit étendre Scribunto_LuaLibraryBase. Voir la documentation de cette classe pour les détails d'implémentation. Dans l'extension Scribunto, ce fichier doit être placé dans engines/LuaCommon/NameLibrary.php, et un mapping ajouté à Scribunto_LuaEngine::$libraryClasses. D'autres extensions peuvent utiliser le hook ScribuntoExternalLibraries. Dans les deux cas, la clé doit correspondre au nom du module ("mw.name" pour une bibliothèque en Scribunto ou "mw.ext.name" pour une bibliothèque d'extension).

La partie Lua de la bibliothèque définit la table contenant les fonctions qui peuvent être appelées depuis les modules Lua. Dans une extension Scribunto, le fichier dans être placé dans engines/LuaCommon/lualib/mw.name.lua. Ce fichier ressemble en général à :

local object = {}
local php

function object.setupInterface( options )
    -- Reitre la fonction setup
    object.setupInterface = nil

    -- Copie le callback PHP dans une variable locale et retire la variable globale
    php = mw_interface
    mw_interface = nil

    -- Ajouter les autres initialisation ici

    -- Installation dans la variable globale mw
    mw = mw or {}
    mw.ext = mw.ext or {}
    mw.ext.NAME = object

    -- Indique que la bibliothèque est chargée
    package.loaded['mw.ext.NAME'] = object
end

return object

Le module dans engines/LuaCommon/lualib/libraryUtil.lua (chargez-le avec local util = require 'libraryUtil') contient diverses fonctions utiles pour réaliser cela.

Prenez soin de lancer les test cases Scribunto avec votre bibliothèque chargée même si votre bibliothèque ne fournit aucun test cases. Les tests standards contiennent des tests pour des choses comme des bibliothèques ajoutant des variables globales indésirables. Si la bibliothèque est chargée avec PHP, les valeurs des fonctions Lua ne seront pas réinitialisées lors d'un nouvel appel à {{#invoke}}. Il faut faire en sorte que les module ne puisse pas utilisé ceci pour transférer des information entre différents appel à {{#invoke}}.

Tests

L'extension Scribunto contient une classe de base pour les tests, Scribunto_LuaEngineTestBase, qui effectue des tests avec les moteurs LuaSandbox et LuaStandalone. Les tests de la bibliothèque devraient étendre cette classe et ne devraient pas remplacer static function suite(). Dans l'extension Scribunto, les tests doivent être dans tests/engines/LuaCommon/NameLibraryTest.php et ajoutés au tableau dans ScribuntoHooks::unitTestsList() (dans common/Hooks.php) ; les extensions doivent ajouter leurs tests dans leur propre fonction UnitTestsList hook, en tenant compet de la valeur de $wgAutoloadClasses['Scribunto_LuaEngineTestBase'].

La plupart du temps, tout ce qui est nécessaire pour faire un cas de test est :

class ClassNameTest extends Scribunto_LuaEngineTestBase {
    protected static $moduleName = 'ClassNameTest';

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

Ceci va charger le fichier ClassNameTests.lua comme si c'était une page « Module:ClassNameTests », avec pour objectif de recevoir un objet avec les propriétés suivantes :

  • count : entier, nombre de tests ;
  • provide( n ) : fonction qui retourne trois valeurs : n, le nom du test n, et une chaine qui est la sortie attendue du test n ;
  • run( n ) : fonction qui exécute le test n et retourne une chaine.

Si getTestModules() est déclaré visible, "Module:TestFramework" est disponible et fournit de nombreuses fonctions d'aide. Si utilisé, ClassNameTests.lua ressemblerait à quelque chose comme :

local testframework = require 'Module:TestFramework'

return testframework.getTestProvider( {
    -- les tests sont ici
} )

Chaque test est lui-même une table avec les propriétés suivantes :

  • name : le nom du test ;
  • func : la fonction à exécuter ;
  • args : une table optionnelle de paramètres à passer à la fonction ;
  • expect : le résultat attendu ;
  • type : le type (optionnel) du test ("Normal" par défaut).

Le type contrôle le format de expect et comment func est appelée. Les types sont :

  • Normal : expect est une table des valeurs retournées, ou une chaine si le test devrait générer une erreur. func est simplement appelée ;
  • Iterator : expect est une table de tables de valeurs retournées. func est appelée comme un itérateur de boucle, et chaque retour d'itération est cumulé.
  • ToString : comme "Normal" mis à part que chaque valeur retournée est passée à tostring().

Tests dans une autre extension

Il existe au moins deux façons d'effectuer des tests PHPUnit :

  1. Exécuter phpunit sur core afin de permettre à tests/phpunit/suites/ExtensionsTestSuite.php de trouver les tests des extensions en utilisant UnitTestsList hook. Si tous les noms de classe de vos tests d'extension contiennent un terme unique commun (par exemple le nom de l'extension), il est possible d'utiliser l'option --filter pour n'exécuter que vos tests d'extension ;
  2. Exécuter phpunit sur le répertoire d'extensions, dans lequel il sélectionnera tout fichier se terminant par "Test.php".

Ces deux approches fonctionneront correctement si Scribunto est chargé dans LocalSettings.php. Et il est facile d'utiliser la première méthode si Scribunto n'est pas chargé car le hook UnitTestsList peut être écrit afin d'éviter de retourner le test Scribunto quand $wgAutoloadClasses['Scribunto_LuaEngineTestBase'] n'est pas défini.

Mais Jenkins utilise la deuxième méthode. Pour que Jenkins exécute correctement les tests, vous devrez ajouter Scribunto comme une dépendance pour votre extension. Voir Gerrit change 56570 pour un exemple.

Si vous avez besoin de lancer les tests en utilisant la deuxième méthode sans que Scribunto ne soit chargé, il est possible de le faire en ajoutant cette vérification au début de vos fichiers de tests :

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

Documentation

Les modules pour Scribunto doivent inclure une documentation dans la section Bibliothèques Scribunto (plus haut). Les bibliothèques d'extension doivent inclure une documentation dans une sous-page de leur propre page d'extension, et lier vers cette documentation depuis #Extension libraries (mw.ext).

Voir aussi

Licence

Ce manuel est dérivé du Lua 5.1 reference manual, qui est disponible sous la licence MIT.

Le manuel dérivé de ce manuel devrait être également distribué avec la même licence.