Extension:Scribunto/Lua reference manual/fr

'''Cette documentation correspond à la traduction de la documentation en anglais datant du 2 juillet 2013 ([//www.mediawiki.org/w/index.php?title=Extension:Scribunto/Lua_reference_manual&oldid=716638 voir la version anglaise correspondante]). Elle ne contient donc pas les éventuels ajouts effectués depuis.'''

'''Note du traducteur (NDT) : cette traduction n'a pas été entièrement relue par d'autres rédacteurs. En cas de doute reportez-vous à la version anglaise. N'hésitez-pas à corriger les erreurs.'''

-

Ce texte documente Lua tel qu'il est utilisé dans MediaWiki via l'extension Scribunto. Certaines parties sont issues de Lua 5.1 reference manual, documentation disponible sous la licence MIT.

Débuter
Sur un wiki utilisant Mediawiki et avec Scribunto implanté, créez une page dont le titre commence par « Module: ». Vous pouvez par exemple l'intituler « Module:Banane » comme dans le Module:Banane de Wikipédia en français. Dans cette page, copiez le texte suivant :

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

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

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

Structure d'un module
Le module lui-même doit retourner une table contenant une fonction qui peut être appelée via la syntaxe. Généralement, comme cela a été montré ci-dessus, une variable locale est déclarée associée à une table, des fonctions sont ajoutées à cette table, et la table est retournée à la fin du module.

Toute fonction qui n'est pas ajoutée à cette table, qu'elle soit locale ou globale, ne sera pas accessible via, mais les fonctions globales resteront accessibles depuis d'autres modules via la fonction 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.

Retourner du texte
La fonction du module doit normalement retourner une chaîne. Quelles que soient les valeurs retournées, celles-ci passeront par tostring et les résultats seront concaténés sans séparateur. Cette chaîne résultante est incorporée dans le wikitext en replacement du.

À ce moment du traitement de la page, les modèles ont déjà été évalués, les fonctions du parseur et 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, la page contiendra "Salut, monde !  ".

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

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

Ceci peut se configurer en utilisant les messages systèmes (les messages de l'espace MediaWiki) :
 * scribunto-doc-page-name : fixe le nom de la sous-page de documentation. Cette sous-page est traitée comme étant du wikitexte et non du code Lua (et ne doit donc pas être invoquée avec . Sa valeur par défaut est "doc".
 * scribunto-doc-page-does-not-exist : message affiché lorsque la sous-page de documentation n'existe pas. Le nom de la sous-page est . Sa valeur par défaut est une courte phrase avec un lien (rouge) vers la page de documentation à créer.
 * scribunto-doc-page-show : message affiché lorsque la sous-page de documentation existe. Le nom de la sous-pages est . Le comportement par défaut est la transclusion de la documentation.
 * scribunto-doc-page-header : entête affiché quand on lit la sous-page de documentation elle-même. Le nom du module dont c'est la page de documentation est  ; la valeur par défaut est une courte explication en italique.

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

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

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 chaîne. Si  est immédiatement suivi par un crochet long ouvrant le commentaire se termine au crochet long fermant correspondant, sinon le commentaire se termine à la fin de la ligne où il a commencé.

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

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

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

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

nil
« Nil » est le type de donnée pour, qui existe pour représenter l'absence de valeur. « Nil » ne doit pas être utilisé comme clé dans une table et il n'y a pas de différence entre un élément sans valeur (jamais assigné) et un élément avec la valeur nil.

Sa conversion en chaîne est "nil", et sa conversion en booléen est false.

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

La conversion en chaîne d'un booléen est "true" ou "false". Contraitement à d'autres langages, les booléens ne peuvent être convertis directement en nombres. Toujours contrairement à d'autres langages seuls false et nil sont faux, le nombre 0 et la chaîne vide étant tout deux considérés comme true.

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

Les chaînes 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), '\b' (backspace, espacement arrière), '\f' (form feed, saut de page), '\n' (newline, saut de ligne), '\r' (carriage return, retour à la ligne), '\t' (horizontal tab, tabulation horizontale), '\v' (vertical tab, tabulation verticale), '\\' (backslash, barre oblique inversée), '\"' (double quote, guillemets droits), et '\&#x27;' (single quote, apostrophe droite).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 chaîne constante peut aussi être définie en utilisant des crochets longs. Un crochet long ouvrant est un crochet ouvrant suivi de 0 ou plus signe « égal » ("=") suivi 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 chaînes délimitées par des crochets longs ne sont pas interprétées, ce qui veut dire que les séquences d'échappement sont traitées comme du texte normal. Le seul cas particulier est la présence d'un retour à la ligne juste après le crochet long ouvrant, auquel cas ce retour à la ligne n'est pas intégré à la chaîne.

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

Nombre
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 sont notés avec un point comme indicateur décimal et sans séparateur de groupe (exemple :  ). Les nombres peuvent aussi utiliser la notation en exposant sans espace (exemples :,  , ou  ). Les entiers peuvent aussi être donnés en notation hexadécimale en utilisant le préfix  (exemple :  ).

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

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

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

Les tables sont créées avec les accolades. La table vide est. Pour remplir une table à la création, une liste d'éléments séparés par des virgules et/ou des point-virgules peut être insérée entre les accolades. Ceci peut prendre plusieurs formes :
 * utilise la (première) valeur de expression1 comme la clé et la (première) valeur de expression2 comme valeur.
 * est équivalent à
 * est à peu près équivalent à, où i est un entier valant 1 au départ et incrémenté de 1 après chaque ajout de cette forme. Si le dernier champ spécifié est une expression valant plusieurs valeurs toutes ces valeurs sont utilisées. Dans tous les autres cas seule la première l'est.

On accède aux champs d'une table en utilisant des crochets, comme avec. Lorsque la clé est une chaîne, on peut aussi y accéder en utilisant le point, par exemple en écrivant. Cela est équivalent à .Pour appeler une fonction contenue dans une table, on peut utiliser le deux-points, par exemple :. Cette notation est équivalente à.

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

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

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

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

Quand une table est convertie en chaîne, le résultat est "table". Ceci peut être modifié en changeant la méta-méthode. Même la table vide est considérée comme « true » en tant que booléen.

Fonction
En Lua les fonctions sont des first-class values (?) : elles peuvent être créées anonymement, être passées en paramètre, assignées à des variables…

Les fonctions sont créées grâce au mot-clé  et appelées en utilisant les parenthèses. Voir plus loin.

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.

La conversion en chaîne d'une fonction retourne "function".

Types non supportés
Le type userdata permet de stocker des données opaques pour les extensions pour Lua écrites dans d'autres langages. Par exemple un userdata peut contenir un pointeur ou une structure C. Ceci n'est pas utilisé en Scribunto.

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

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

Quand elles sont accédées pour leurs méta-fonctions, les méta-tables sont accédées avec rawget.

Les champs d'une méta-table qui impactent la table elle-même sont :
 * : utilisé quand l'accès  aurait retourné nil. Si la valeur de ce champ est une table, l'accès sera tenté de nouveau dans cette table (par exemple  ). Si la valeur de ce champ est une fonction, celle-ci est appelée ainsi :  . La fonction rawget court-circuite cette méta-méthode.
 * : utilisé lorsqu'une valeur est assignée à une clé de la table et qu'il n'y a pas de valeur pour cette clé ( avec   qui aurait retourné nil). Si la valeur de ce champ est une table l'affectation sera répétée dans cette table . Si la valeur de ce champ est une fonction celle-ci est appelée comme suit :  . La fonction rawset court-circuite cette méta-méthode.
 * : utilisé quand la syntaxe d'un appel de fonction est utilisé sur une table . Cette valeur doit être une fonction, qui est appelée comme suit :.
 * : utilisé pour que les tables puissent contenir des références faibles (weak references). Cette valeur doit être une chaîne. Par défaut toute valeur utilisée comme clé ou valeur dans une table ne sera pas nettoyée par le nettoyeur de mémoire (garbage collector). Mais si ce méta-champ contient la lettre « k » les clés peuvent être « nettoyées », et si il contient la lettre « v » les valeurs peuvent être « nettoyées ». Dans les deux cas la paire clé-valeur correspondante sera effacée de la table si l'un des éléments est « nettoyé ». Notez que le comportement est non défini en cas de modification de ce champ dans une méta-table.

Les autres champs de méta-tables sont : † Pour les opérateurs binaires, Lua regarde d'abord la méta-table du paramètre de gauche (s'il y en a une), puis celle du paramètre de droite quand il cherche quelle méta-méthode utiliser. ‡ Pour les opérateurs relationnels, la méta-méthode est utilisée uniquement si la même fonction est donnée pour les deux paramètres dans leurs méta-tables respectives. Des fonctions anonymes, même avec un contenu identique, ne sont pas considérées comme identiques. *  affecte getmetatable et setmetatable.
 * __add†
 * __sub†
 * __mul†
 * __div†
 * __mod†
 * __pow†
 * __unm
 * __concat†
 * __eq‡
 * __lt‡
 * __le‡
 * __pairs
 * __ipairs
 * __metatable*
 * __tostring

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

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

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

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

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

Les variables locales ont une portée lexicale. Voir Déclaration de variables locales.

Expressions
Une expression est quelque chose qui a une valeur : les littéraux (nombres, chaînes, 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 (vararg expression), 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 ont une valeur. Les appels de fonctions et les expressions vararg peuvent en avoir un nombre quelconque. Notez que mettre un appel de fonction ou une expression vararg entre parenthèses fait perdre toutes les valeurs sauf la première de leurs valeurs.

Les listes d'expressions sont des listes d'expressions séparées par des virgules. Toutes ces expressions sauf la dernière sont forcées à avoir une seule valeur (en ignorant toutes les valeurs additionnelles, et en utilisant 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, exposant et négation.

Pour tous les opérandes qui sont des nombres ou des chaînes qui peuvent se convertir en nombre (tonumber retourne autre chose que nil) ces opérations ont leur fonctionnement habituel.

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

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. Si ils sont différents le résultat est faux. Ensuite il compare leur valeur : nil, booléen, nombre et chaînes sont comparées de la façon usuelle. Les fonctions sont égales si elles font référence à exactement le même objet ( retournera faux car il s'agit de la comparaison de deux fonctions anonymes différentes). Les tables sont comparées de la même façon mais ceci peut être modifié en utilisant la méta-méthode.

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

Pour les opérateurs d'ordre, si les deux opérandes sont des nombres ou des chaînes ils sont comparés directement. Ensuite la présence de méta-méthodes est vérifiée : Si aucune méta-méthode n'est trouvée, une erreur est générée.
 * utilise
 * utilise  si disponible, ou si   est disponible alors   est utilisé
 * est considéré comme équivalent à
 * est considéré comme équivalent à

Opérateurs logiques
Les opérateurs logiques sont,  , et. Tous considèrent nil et false comme faux et toutes les autres valeurs comme vraies.

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

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

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

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

Opérateur de concaténation
L'opérateur de concaténation est constitué des deux points. Si les deux opérandes sont des nombres ou des chaînes, ils sont convertis en chaînes et concaténées. Sinon, si une méta-méthode  est disponible, elle est utilisée. Sinon une erreur est générée.

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

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

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

Préséance des opérateurs
Voici la préséance des opérateurs, de la plus haute priorité à la plus basse :
 * not # - (négation)
 * + - (soustraction)
 * and
 * or
 * and
 * or
 * and
 * or

Pour une même préséance, la plupart des opérateurs sont associatifs à gauche. Par exemple  est interprété comme. L'exposant et la concaténation sont associatifs à droite, par exemple  est interprété comme.

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

func( exp-list )

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

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

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

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

table:name( exp-list )

est strictement équivalente à :

table.name( table, exp-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 chaîne constante. Par exemple, les appels :

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

sont équivalents à :

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

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

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

Déclarations de fonctions
La syntaxe pour déclarer une fonction est :

function ( 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 ) -- la variable n de portée "externe" est disponible ici pour ajout à 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 (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, ... ) -- on récupère les paramètres additionnels dans une table local args = { ... }    -- on compte le nombre de paramètres (comme il faut) 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  doit être utilisée au lieu de   pour compter le nombre de valeurs dans l'expression vararg.

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'assignement des variables locales, "factorial" fait référence à une variable globale de ce nom (probablement « vide »). Ce problème peut être évité en déclarant la variable locale avant et en lui assignant sa valeur dans une instruction postérieure.

Instructions
Une instruction est l'unité élémentaire d'exécution : une tâche, un élément de contrôle, un appel de fonction, une déclaration de variable…

Un morceau (chunk, terme anglais utilisé par la suite plutôt que la traduction qui « perd » un peu de son sens) est une séquence d'instructions, éventuellement séparées par des point-virgules. Un chunk est considéré comme le corps d'une fonction anonyme, donc il peut déclarer des variables locales, recevoir des paramètres et retourner une valeur.

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

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

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

Le nombre de valeurs dans la liste d’expressions et la liste de variables n’est pas nécessairement le même :
 * s’il y a plus d’expressions que de variables, les variables seront affectées des valeurs des premières expressions, et les valeurs des autres expressions sont non affectées (mais elles sont évaluées malgré tout) ;
 * s’il y a moins d’expression que de variables, les premières variables prendront les valeurs successives de ces expressions, les variables suivantes vaudront nil.

Par exemple : do    local vals = {} local add = function( x ) table.insert( vals, x ) return x    end local w, x, y = add( 'W' ), add( 'X' ), add( 'Y' ), add( 'Z' ) -- affichera W, X, Y, Z mais Z n’est affecté à aucune variable add( '(' .. (w or 'nil') .. ' ' .. (x or 'nil') .. ' ' .. (y or 'nil') .. ')' ) -- affichera (W X Y)    local w, x, y = add( 'W' ), add( 'X' ) -- affichera W, X     add( '(' .. (w or 'nil') .. ' ' .. (x or 'nil') .. ' ' .. (y or 'nil') .. ')' ) -- affichera (W X nil) mw.log( table.concat( vals, ', ' ) ) end affichera « W, X, Y, Z, (W X Y), W, X, (W X nil) » dans la console de débogage.

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

Une variable locale peut être déclarée localement à nouveau dans le même bloc, elle remplace dans la suite du bloc la variable précédente, mais si elle remplace un objet (une table ou une fonction), la valeur et les assignations internes de cet objet ne sont pas écrasées, seule la référence à cet objet par la variable locale est écrasée (l’objet précédemment référencé ne sera dont pas modifié par la déclaration ou toute modification de la variable déclarée). Une déclaration  crée donc un nouveau bloc de portée imbriqué au sein du bloc actuel.

De même, lors de la déclaration d’une ou plusieurs variables avec des valeurs initiales, aucune des nouvelles variables déclarées ne sera visible lors de l’évaluation des valeurs initiales (l’évaluation des valeurs affectées s’effectue entièrement en utilisant les variables visibles avant la déclaration, avant que soient finalement déclarées et assignées les nouvelles variables avec les valeurs évaluées).

Le code suivant par exemple : do    local vals = {} local add = function( x ) table.insert( vals, x ) return x    end x = { 'A' } add( x[1] ) -- A    do         local y = x -- ne copie que la référence au tableau x         y[1] = 'B' -- écrasement aussi de la valeur dans le tableau x         add( x[1] ) -- B         x = { 'C' } -- écrasement de la variable x du bloc englobant, car non local add( x[1] ) -- C        local x = { 'D' } -- pas d'écrasement du tableau contenu mais il n’est plus accessible avec la variable x         add( x[1] ) -- D         local x, y = { 'E' }, x -- pas d'écrasement du tableau contenu, dont la référence est gardée ici dans une nouvelle variable locale add( x[1] ) -- E        add( y[1] ) -- D     end add( x[1] ) -- C    mw.log( table.concat( vals, ', ' ) ) end affichera « A, B, C, D, E, D, C » dans la console de débogage.

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

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

La première forme de boucle for déclare une variable locale et répète le bloc pour des valeurs de cette variable allant de exp1 à exp2 en ajoutant exp3 à chaque itération. exp3 peut être omise auquel cas la valeur 1 est utilisée. Toutes les expressions sont évaluées une fois avant que la boucle ne démarre.

Cette forme de la boucle for est à peu près équivalente à : do    local var, limit, step = tonumber( exp1 ), tonumber( exp2 ), tonumber( exp3 ) if not ( var and limit and step ) then error end while ( step > 0 and var <= limit ) or ( step <= 0 and var >= limit ) do        local name = var block var = var + step end end

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

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

Cette forme est à peu près équivalente à :

do    local func, static, var = exp-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.

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

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

Lua met en œuvre les « appels de queue » (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  et.

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

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

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

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

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

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

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

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

-- fonction comme méthode d'une table function table:func( var-list ) block end table.func = function ( self, var-list ) block end

Notez que la notation avec les deux-points est ici parallèle à la notation avec les deux-points pour les appels de fonction, en ajoutant explicitement un paramètre "self" au début de la liste des paramètres.

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

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

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

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

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

foo = 1 mw.log( foo ) -- enregistre "1" _G.foo = 2 mw.log( foo ) -- enregistre "2" _G = {}      -- _G ne pointe plus sur la table des variables globales _G.foo = 3 mw.log( foo ) -- enregistre toujours "2"

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

-- Appelle une fonction dont le nom est stocké dans une variable _G[var]

-- enregistre le nom et transforme en chaîne toutes les variables globales for k, v in pairs( _G ) do   mw.log( k, v ) end

-- enregistre la création de nouvelles variables globales setmetatable( _G, {    __newindex = function ( t, k, v )          mw.log( "Création d'une nouvelle variable globale '" .. k .. "'" )         rawset( t, k, v )     end } )

_VERSION
Une chaîne qui contient la version courante de Lua (exemple : "Lua 5.1").

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

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

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

-- ceci ne vérifie pas les erreurs local result1, result2, etc = func( ... ) -- ceci fait de même mais vérifie les erreurs local result1, result2, etc = assert( func( ... ) )

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

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

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

Retourne un environnement (une table globale) comme indiqué par  :
 * si 1, nil ou absent, retourne l'environnement de la fonction qui appelle . La plupart du temps ceci a le même effet que _G.
 * Un entier entre 2 et 10 retourne l'environnement des fonctions précédentes dans la pile d'appels. Par exemple 2 retourne l'environnement de la fonction qui a appelé la fonction courante et ainsi de suite. Une erreur est générée si cette valeur est plus grande que le nombre d'appels de fonctions dans la pile d'appels, ou si la pile correspondante est un appel de queue.
 * 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 librairies standards et librairies Scribunto sont protégés. Tenter d'y accéder avec  retournera nil systématiquement.

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

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

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

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

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

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

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

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

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

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

for k, v in pairs( t ) do    block end

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

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

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

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

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

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

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

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

En d'autres mots  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
Fixe la méta-table d'une table. peut être nil mais doit être explicitement indiquée.

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

tonumber
Tente de convertir  en nombre. Si c'est un nombre ou une chaîne convertible en nombre, alors  retourne ce nombre ; sinon retourne nil.

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

En base 10, les valeurs peuvent avoir une partie décimale, être exprimées en notation exposant, et peuvent avoir un préfixe "0x" pour indiquer la base 16. Dans les autres bases, seuls les entiers sont acceptés.

tostring
Permet de convertir  en chaîne. Voir Data types pour les détails sur comment chaque type est converti.

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

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

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

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

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

La fonction  pourrait ressembler à quelque chose comme suit :

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

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

Fonctions mathématiques
Cette librairie est une interface pour la librairie mathématique C standard. Elle fournit toutes ses fonctions dans une table.

math.abs
Retourne la valeur absolue de.

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

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

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

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

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

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

math.cosh
Retourne le cosinus hyperbolique de.

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

math.exp
Retourne la valeur ex.

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

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

math.frexp
Retourne  et   tels que :
 * si  est fini et différent de zéro : $$x = m \times 2^e$$,   est un entier et la valeur absolue de   est dans l'intervalle $$[0.5, 1[$$
 * si  vaut zéro :   et   valent 0
 * si  est NaN ou infini :   est   et   est indéfini

math.huge
La valeur , une valeur plus large ou égale à n'importe quelle valeur numérique.

math.ldexp
Retourne m2e ( doit être un entier).

math.log
Retourne le logarithme naturel de.

math.log10
Retourne le logarithme en base 10 de.

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

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

math.modf
Retourne deux nombres, la partie entière de  et la partie fractionnaire de.

math.pi
La valeur de pi.

math.pow
Retourne xy. (Vous pouvez aussi utiliser l'expression  pour calculer cette valeur.)

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

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

Les paramètres  et   peuvent être omis, mais si ils sont présents ils doivent se convertir en entiers.
 * Sans paramètre, retourne un réel dans l'intervalle $$[0,1[$$
 * Avec un paramètre, retourne un entier dans l'intervalle $$[1,m]$$
 * Avec deux paramètres, retourne un entier dans l'intervalle $$[m,n]$$

math.randomseed
Fixe  comme « graine » pour le générateur de nombres pseudo-aléatoires : une même graine produit la même séquence de nombres.

math.sin
Retourne le sinus de  (supposé être en radians).

math.sinh
Retourne le sinus hyperbolique de.

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

math.tan
Retourne la tangente de  (supposé être en radians).

math.tanh
Retourne la tangente hyperbolique de.

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

os.date

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

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

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

Si le 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 le format est la chaîne "*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 le format n'est pas "*t", alors la date est retournée en tant que chaîne, formatée en accord avec les règles de la fonction C strftime.

os.difftime
Retourne le nombre de secondes séparant  de.

os.time
Retourne un nombre représentant l'heure courante.

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

require
Charge le module indiqué.

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

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

Voir la documentation de  pour les chargeurs disponibles.

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

Par exemple, si vous avez un « Module:Exemple » écrit comme suit : Vous pouvez charger ce module depuis un autre via le code suivant dans cet autre module :

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

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

Scribunto fournit deux fonctions de recherche :
 * 1) La recherche avec   pour la fonction de chargement
 * 2) La recherche avec les modules fournis par Scribunto pour le nom du module, et si cela échoue, la recherche dans l'espace de noms "Module:". Dans ce dernier cas, le préfixe "Module:" doit être présent dans le nom du module.

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

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

package.seeall
Fixe la méta-méthode  pour   à _G.

Librairie de manipulation de chaînes
Dans toutes les fonctions sur les chaînes, 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 chaîne : -1 est le dernier caractère, -2 l'avant-dernier… Pour manipuler des chaînes Unicode, utilisez les méthodes correspondantes de la librairie Scribunto Ustring.

string.byte
Retourne le code numérique interne associé au caractère , , &middot;&middot;&middot;,. La valeur par défaut de  est 1, la valeur par défaut de   est. Identique à mw.ustring.byte.

string.char
Reçoit zéro ou plus entiers. Retourne une chaîne de même longueur que le nombre de ses paramètres, dans laquelle chaque caractère a le code numérique interne égal au paramètre correspondant. Voir mw.ustring.char pour une fonciton similaire qui utilise les points de code Unicode plutôt que les valeurs en bits.

string.find
Cherche la première correspondance de  dans la chaîne. Si une correspondance est trouvée, alors  retourne les indices de  où cette occurrence commence et se termine, sinon il retourne nil.

Un troisième paramètre optionnel  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  désactive la fonctionnalité de pattern matching, et transforme la fonction en une opération de recherche littérale de sous-chaîne, aucun des caractères de   n'étant alors considéré comme ayant de sens particulier.

Notez que si  est fourni, alors   doit l'être aussi.

Si un motif (pattern) comporte une capture, alors si une correspondance est trouvée le résultat de la capture est également retourné après les deux indices.

Voir mw.ustring.find pour une fonction similaire qui utilises les motifs ustring and where the  offset is in characters rather than bytes.

string.format
Retourne une version formatée de ses paramètres qui peuvent être en nombre variable, en suivant la description donnée dans son premier paramètre (qui doit être une chaîne). La chaîne de format suit les mêmes règles que les fonctions de la famille  en C standard. Les seules différences sont que les options/modificateurs ,,  ,  ,  , et   ne sont pas supportés et qu'il existe une option supplémentaire,. L'option  formate une chaîne de façon à ce qu'elle soit sainement utilisable par l'interpréteur Lua : la chaîne est écrite entre guillements, et les guillemets, retours à la ligne, codes zéros et les barres obliques inversées (backslash) présents dans le paramètre  sont échappées correctement. Par exemple l'appel

produira la chaîne :

Les options,  ,  ,  ,  , ,,  ,  ,  ,  , et  attendent toutes un nombre en paramètre, alors que   et   attendent une chaîne.

Cette fonction n'accepte pas les chaînes qui contiennent des codes zéros, à part comme argument pour l'option.

Identique à mw.ustring.format.

string.gmatch
Retourne une fonction d'itération qui, chaque fois qu'elle est appelée, retourne la capture suivante de  dans la chaîne. Si  ne spécifie pas de capture, alors la correspondance complète est retournée.

Par exemple la boucle suivante

va itérer sur chaque mot de la chaîne , affichant chaque mot seul sur une ligne.

L'exemple suivant récupère toutes les paires  de la chaîne fournie et les range dans une table :

Pour cette fonction, un ' ' au début du motif n'a pas de sens spécial, car cela bloquerait l'itération.

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

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

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

Si  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  est une fonction, alors cette fonction est appelée à chaque fois qu'une correspondance est trouvée, avec toutes les sous-chaînes 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 chaîne ou un nombre, alors il est utilisé comme chaîne 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 chaîne).

Quelques exemples :

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

string.len
Reçoit une chaîne et retourne sa longueur. La chaîne vide  a une longueur de 0. Les zéros sont cependant comptabilisés. Ainsi  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 bits.

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

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

string.match
Cherche la première correspondance de  dans la chaîne. Si une correspondance est trouvée,  retourne la capture correspondante, sinon il retourne nil. Si  ne précise pas de capture, alors la chaîne complète est retournée. Un troisième paramètre optionnel  permet de spécifier la position de départ dans la chaîne où commencer la recherche. Sa valeur par défaut est 1 et 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  est en caractères plutôt qu'en octets.

string.rep
Retourne une chaîne qui est la concaténation de  copies de la chaîne. Identique à mw.ustring.rep.

string.reverse
Retourne une chaîne qui est la chaîne  renversée (début ↔ fin). Ne fonctionne pas avec des caractères Unicodes.

string.sub
Retourne une sous-chaîne de  qui débute à la position et continue jusqu'à la position , et  pouvant être négatifs. Si  est absent il est considéré comme valant -1 (qui signifie la longueur de la chaîne). En particulier  retourne un préfixe de   de longueur  , et  retourne un suffixe de longueur   de.

Voir mw.ustring.sub pour une fonction similaire pour laquelle the offsets are characters rather than bytes.

string.upper
Reçoit une chaîne et retourne une copie de cette chaîne avec tous les caractères en minuscule changés en majuscule. Tous les autres caractères sont laissés tels quels. La définition de ce qui est une minuscule dépend du projet.

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 fr:PCRE :
 * Le caractère d'échappement est le symbole du pour cent, pas l'antislash   ;
 * Le point  remplace tout caractère, y compris le retour chariot ;
 * Il n'y a pas d'option pour être insensible à la casse ;
 * L'alternative  n'est pas définie ;
 * Les quantificateurs (, ,  , et  ) ne peuvent s'appliquer qu'à un caractère ou une classe de caractère, pas à un groupe de capture ;
 * Le seul quantificateur non possessif est, qui est équivalent au quantificateur   de PCRE ;
 * Pas moyen de quantifier de manière précise (comme le ferait  avec PCRE ;
 * Les seuls caractères de contrôle qui n'ont aucune profondeur sont  et   (lua n'offre pas la possibilité d'utiliser   ou   qui apparaisse dans les PCRE).

Voir aussi motifs ustring pour des motifs similaires utilisant cette fois les caractères Unicode.

Classes de caractères :
Une classe de caractères est utilisée pour représenter un ensemble de caractères. Les combinaisons suivantes sont autorisées pour représenter une classe de caractères :

Toutes les classes x décrites plus haut peuvent aussi être utilisées dans un set. Tous les autres caractères dans un set représentent eux-mêmes. Par exemple  (ou  ) représente tous les caractères alphanumériques et le tiret bas (underscore),   représente les chiffres octaux, et   représente les chiffres octaux plus les lettre minuscules plus le caractère. Utiliser à la fois les intervalles et les classes a un effet non spécifié. Ainsi, des motifs comme  ou   n'ont pas de sens.
 * x : (où x n'est pas un caractère « magique » ) représente le caractère x lui-même.
 *   : (un point) représente tous les caractères.
 *   : représente toutes les lettres.
 *   : représente tous les caractères de contrôle.
 *   : représente tous les chiffres.
 *   : représente toutes les lettres minuscules.
 *   : représente tous les signes de ponctuation.
 *   : représente tous les caractères séparateurs (espace, saut de ligne, …).
 *   : représente toutes les lettres majuscules.
 *   : représente tous les caractères alphanumériques
 *   : représente tous les chiffres hexadécimaux.
 *   : représente le caractère  (le caractère dont la valeur numérique est nulle).
 *   : (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). Tout caractère de ponctuation (même les non magiques) peut être précédé d'un  quand il représente lui-même.
 *   : représente la classe qui est l'union de tous les caractères présents dans set. On peut indiquer un intervalle de caractère en séparant les caractères qui bornent cet intervalle avec un.
 *   : représente le complément de set (voir l'interprétation de set ci-dessus), c'est-à-dire tous les caractères n'appartenant pas à set.

Pour toutes les classes représentées par une seule lettre (, , …), la lettre majuscule correspondante représente le complément de cette classe. Par exemple  représente tous les caractères qui ne sont pas des séparateurs.

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

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 chaîne traitée. Un  à la fin du motif correspond à la fin de la ligne de la chaîne traitée. Aux autres positions,  et   n'ont pas de sens particulier et représentent le caractère qui les constitue.

Captures :
Un motif (pattern) peut contenir des sous-motifs entourés de parenthèses, qui décrivent des captures. Quand une correspondance réussit, la sous-chaîne de la chaîne qui correspond est stockée (capturée) pour usage ultérieur. Les captures sont numérotées dans l'ordre de leur parenthèse de gauche. Par exemple, dans le motif, la partie de la chaîne qui concorde avec   est stockée dans la première capture (et a donc le numéro 1) ; le caractère qui concorde avec " " est stocké dans la capture numéro 2, et la partie qui concorde avec " " a le numéro 3.

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

Un motif ne peut contenir de zéros. Utilisez  à la place.

Librairie Table
La plupart des fonctions de la librairie table supposent que la table est une séquence.

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

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

La valeur par défaut de  est la chaîne vide, la valeur par défaut de   est 1, et la valeur par défaut de   est la longueur de la table. Si  est plus grand que   retourne une chaîne vide.

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

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

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

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

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
Enlève de  l'élément se trouvant à la position , 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  est la longueur de la table, donc le code   supprime le dernier élément de la table.

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

table.sort
Trie les éléments de la table dans l'ordre indiqué, sur place, de  à. Si  est indiqué alors ce doit être une fonction qui reçoit deux éléments de la table et qui retourne vrai quand le premier est inférieur au second (ainsi   retournera vrai après le tri). Si  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.

Librairies Scribunto
Toutes les librairies Scribunto se trouvent dans la table.

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

mw.clone
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
Retourne l'objet frame courant.

mw.incrementExpensiveFunctionCount
Ajoute un au compteur des « parser-function coûteuses », et génère une exception si ce compteur dépasse la limite (voir $wgExpensiveParserFunctionLimit).

mw.loadData
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  peut prendre un temps non négligeable. Pour éviter ce problème, la fonction  existe.

fonctionne comme  avec les différences suivantes :
 * Le module n'est évalué qu'une fois par page, plutôt qu'une fois par appel à.
 * Le module n'est pas enregistré dans.
 * 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 chaînes 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 chaînes.
 * La table réellement retournée par  a des méta-méthodes qui fournissent un accès en lecture seul à cette table. Dans la mesure où elle ne contient pas directement les données,   et   fonctionnent mais les autres méthodes, y compris ,  , et les fonctions de la librairie 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  pour charger efficacement les données.

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  est un alias de cette fonction.

L'objet Frame
L'objet frame est l'interface des paramètres passés au, ainsi que l'interface au 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 :

alors  retournera "arg1",   retournera "arg2", et   (ou  ) retournera "arg3". Il est également possible d'itérer sur les paramètres en utilisant  ou.

Notez que les valeurs de cette table sont toujours des chaînes. 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 : donne les chaînes "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 éventuelles en début et fin).

Pour des raisons de performance, frame.args est une méta-table et non une table réelle des 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,  , et les fonctions de la librairie Table.

Si des paramètres contenant des appels de modèles ou des paramètres à triple accolades sont utilisés comme paramètre pour #invoke, ils seront évalués avant d'être envoyés à Lua. Si certains tags utilisant la notation XML sont présents (comme,  ,   et  ) il sont convertis en « strip markers », des chaînes 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.

frame:callParserFunction

 * 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 suivant sont à peu près équivalents au wikitexte indiqué :

--      frame:callParserFunction{ name = 'ns', args = 0 } --  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' ) --  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

 * 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  en wikitexte. Comme pour la transclusion, si le titre title 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 --  frame:expandTemplate{ title = 'template', args = { '|' } } -- ceci est à peu près équivalent au wikitexte --  frame:expandTemplate{ title = 'template', args = { ' | ' } }

frame:extensionTag
Ceci est équivalent à frame:callParserFunction avec  comme nom de fonction et avec   avant les paramètres.

-- Ceci est équivalent 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' } }

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

frame:newChild

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

Crée un nouvel objet frame qui est un fils 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. Le nombre de frames qui peuvent être créés est limité.

frame:preprocess
Traite le wikitexte indiqué dans le contexte de l'objet frame. Ainsi les modèles, parser-functions et paramètres tels que  sont évalués et remplacés par leurs résultats. Certains tags en notation XML (tels que,  ,   et  ) seront convertis en « strip markers », des chaînes spéciales commençant avecle 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  à la place. 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.

frame:getArgument
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 :, qui retourne le wikitexte traité de ce paramètre.

frame:newParserValue
Retourne un objet avec une méthode :, qui retourne le résultat de.

frame:newTemplateParserValue

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

Retourne un objet avec une méthode :, qui retourne le résultat de   appelé avec le paramètre indiqué.

frame:argumentPairs
Identique à. Existe pour compatibilité avec des versions précédentes de Scribunto.

Librairie Language
Les codes des langues sont décrits dans Language code.

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

mw.language.fetchLanguageName
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.

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

mw.language.isKnownLanguageTag
Retourne vrai si le code indiqué est un code IETF reconnu par MediaWiki.

mw.language.isSupportedLanguage
Vérifie si la localisation est disponible dans MediaWiki pour la langue indiquée.

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

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

mw.language.isValidCode
Retourne vrai si une chaîne 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 à aucun langage connu.

mw.language.new
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.

mw.language:getCode
Retourne le code de langue correspondant à cet objet.

mw.language:isRTL
Retourne vrai si la langue est écrite de droite à gauche, faux si elle est écrite de gauche à droite.

mw.language:lc
Convertit la chaîne en minuscules, en respectant les règles particulières de la langue correspondante.

Quand la librairie Ustring est chargée, la fonction mw.ustring.lower est codée en appelant.

mw.language:lcfirst
Convertit le premier caractère de la chaîne en minuscule, comme le fait lang:lc.

mw.language:uc
Convertit la chaîne en majuscules, en respectant les règles particulières de la langue correspondante.

Quand la librairie Ustring est chargée, la fonction mw.ustring.upper est codée en appelant.

mw.language:ucfirst
Convertit le premier caractère de la chaîne en majuscule, comme le fait lang:uc.

mw.language:caseFold
Convertit la chaîne 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
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.

mw.language:formatDate
Formate une date selon le format indiqué dans la chaîne format. Si  est omis, l'heure actuelle est utilisée. La valeur  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 chaîne de formatage et les valeurs supportées pour  sont identiques à celles du parser function #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 affiche un "n" lang:formatDate( '\n' ) -- ceci affiche un "n" alors que affiche un "\" -- suivi du numéro du mois. lang:formatDate( '\\n' ) -- ceci affiche un "\" suivi du numéro du mois, alors que -- affiche deux "\" suivi du numéro du mois. lang:formatDate( '\\\\n' )

mw.language:formatDuration
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 chaîne.

, 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', 'days', 'hours', 'minutes', et 'seconds'.

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

mw.language:convertPlural
Permet de choisir la forme gramaticale adaptée depuis  (qui doit être une séquence) ou   en se basant sur le nombre. Par exemple en anglais, vous pouvez utiliser  ou   pour générer un texte grammaticalement correct qu'il y ait 1 ou 200 "socks".

Le nombre de valeurs nécessaires pour la séquence dépend de la langue ; voir m:Help:Magic words et FAQ pour plus de détails.

mw.language:convertGrammar

 * Notez l'ordre différent des paramètres dans les deux versions.  utilise le même ordre des paramètres que la méthode de même nom dans l'objet Language alors que   utilise le même ordre des paramètres que la parser-function de même nom (voir Help:Magic words).

Permet de choisir la forme correcte de  pour l'inflexion.

Les valeurs possibles pour  et   dépendent de la langue, voir m:Help:Magic words et Grammar pour plus de détails.

mw.language:gender
Permet de choisir la chaîne correspondante au genre indiqué par, qui peut être "male", "female" ou un nom d'utilisateur.

mw.language:getArrow
Retourne un caractère Unicode correspondant à la direction :
 * forwards: "→" ou "←" selon l'orientation de la langue
 * backwards: "←" ou "→" selon l'orientation de la langue
 * left: "←"
 * right: "→"
 * up: "↑"
 * down: "↓"

mw.language: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
Retourne une chaîne 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  est vrai ou faux (si vrai retourne la direction opposée à celle de la langue).

mw.language:getDirMarkEntity
Retourne "&amp;lrm;" ou "&amp;rlm;", selon la direction de la langue et selon que  est vrai ou faux (si vrai retourne la direction opposée à celle de la langue).

mw.language:getDurationIntervals
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.

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

Librairie Message
Cette librairie est une interface aux versions localisées des messages et à l'espace de noms MediaWiki:.

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

mw.message.new
Crée un nouvel objet Message pour le message indiqué.

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

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
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  du nouvel objet.

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

mw.message.rawParam
Traite la valeur value de façon qu'elle ne soit pas interprétée comme du wikitexte par.

mw.message.numParam
Traite la valeur value de façon à ce qu'elle soit automatiquement formatée comme avec. Notez que ceci ne dépend pas de la librairie Language actuellement disponible dans Scribunto.

mw.message.getDefaultLanguage
Retourne un objet Language pour la langue courante.

mw.message: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, chaînes ou des valeurs spéciales retournées par mw.message.numParam ou mw.message.rawParam.

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

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

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

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

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

mw.message:inLanguage
Précise la langue à utiliser pour traiter le message. peut être une chaîne ou une table avec une méthode  (par exemple un objet Language).

La langue par défaut est celle retournée par.

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

mw.message:useDatabase
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  pour autoriser des appels chaînés.

mw.message:title
Précise le titre à utiliser pour traiter le message. Ceci impacte les « magic words » comme  et. La valeur peut être nil (pour utiliser la valeur par défaut), une chaîne ou une table avec un champ  (donc un objet Title).

La valeur par défaut est le titre de la page en train d'être traitée.

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

mw.message:parse


Traite le message en format HTML et retourne le texte correspondant dans une chaîne.

Notez que ceci n'est probablement pas très utile car  doit retourner un wikitexte.

mw.message:parseAsBlock


Traite le message en format HTML et retourne le texte correspondant dans une chaîne. Le résultat est toujours retourné dans un tag de bloc.

Notez que ceci n'est probablement pas très utile car  doit retourner un wikitexte.

mw.message:plain
Remplace les paramètres et retourne le message tel quel en wikitexte. Les appels à des modèles et à des parser-functions sont laissés intacts.

mw.message:text
Traite les paramètres, les appels à des modèles, à des parser-functions, etc., et retourne le résultat en wikitexte.

mw.message:escaped
Traite les paramètres, les appels à des modèles, à des parser-functions, etc. À l'exception des paramètres bruts, tout,  ,  ,  , et   est remplacé par l'entité HTML correspondante.

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

mw.message:isBlank
Retourne un booléen indiquant si la clé de message correspond à un contenu. Retourne vrai si la clé n'existe pas ou si le message est la chaîne vide.

mw.message:isDisabled
Retourne un booléen indiquant si la clé de message est désactivée. Retourne vrai si la clé n'existe pas, si le message est la chaîne vide ou la chaîne "-".

mw.site.currentVersion
Une chaîne 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 :
 * 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 : fixé pour l'espace de noms 0 : le nom à utiliser pour affichage, car name vaut la chaîne 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 chaîne. (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  et   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 $wgDisableCounters 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


Retourne des statistiques sur la catégorie. Si  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  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 coûteuses ».

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

mw.site.stats.usersInGroup
Retourne le nombre d'utilisateurs dans le groupe indiqué.

Librairie Text
La librairie text fournit quelques fonctions utiles de traitement de texte absentes de la librairie String et de la librairie Ustring. Ces fonctions peuvent fonctionner avec les caractères UTF-8.

mw.text.decode
Remplace les entités HTML de la chaîne par les caractères correspondant.

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

mw.text.encode
Remplace les caractères de la chaîne 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  est indiqué, il doit contenir une chaîne pouvant être utilisée dans une classe de caractères des motifs Ustring, par exemple "set" dans. Par défaut :  (l'espace à la fin est l'espace insécable U+00A0).

mw.text.listToText
Joint une liste sous forme « textuelle ». Fait la même chose que  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 le MediaWiki:and concaténé avec le MediaWiki:word-separator.

Exemples :

-- retourne une chaîne vide mw.text.listToText( {} ) -- retourne "1" mw.text.listToText( { 1 } ) -- retourne "1 et 2" mw.text.listToText( { 1, 2 } ) -- retourne "1, 2, 3, 4 et 5" mw.text.listToText( { 1, 2, 3, 4, 5 } ) -- retourne "1; 2; 3; 4 ou 5" mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' ou ' )

mw.text.nowiki
Remplace divers caractères dans la chaîne 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 chaîne ou juste après un retour à la ligne : '#', '*', ':', ';'
 * Les séquences suivantes : "://", "ISBN ", "RFC "

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

Par exemple  retourne une table.

Si  correspond à la chaîne vide,   sera découpé en caractères individuels.

mw.text.gsplit
Retourne une fonction itérative qui va itérer sur les sous-chaînes qui auraient été retournées par un appel équivalent à.

mw.text.tag

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

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

Si  est indiqué, il doit être une table avec des clés de type chaîne. 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  n'est pas présent (ou vaut nil), seul le tag ouvrant est retourné. Si  vaut false, un tag auto-fermant est retourné. Sinon il doit être un nombre ou une chaîne 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, utilisez plutôt frame:extensionTag.

mw.text.trim
Enlève les espaces et autres caractères au début et à la fin d'une chaîne.

Si  est indiqué, il doit contenir une chaîne syntaxiquement compatible avec les classes de caractères des motifs Ustring, par exemple "set" dans. Par défaut : l'espace ASCII,.

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

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

Exemples utilisant "..." pour ellipsis :

-- retourne "foobarbaz" mw.text.truncate( "foobarbaz", 9 ) -- retourne "fooba..." mw.text.truncate( "foobarbaz", 5 ) -- retourne "...arbaz" mw.text.truncate( "foobarbaz", -5 ) -- retourne "foo..." mw.text.truncate( "foobarbaz", 6, nil, true ) -- retourne "foobarbaz", car c'est plus court que "foobarba..." mw.text.truncate( "foobarbaz", 8 )

mw.text.unstrip
Remplace les « strip-markers » MediaWiki (nowiki, etc.) par le texte correspondant.

Notez que ces strip markers sont là pour une bonne raison, et les remplacer en Lua plutôt que de permettre au parser de les traiter de la bonne façon peut casser certaines choses.

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

mw.title.compare
Retourne -1, 0 ou 1 selon que le titre  est plus petit, égal ou supérieur au titre

mw.title.getCurrentTitle
Retourne un objet Title pour la page courante.

mw.title.new


Crée un nouvel objet Title. Le compteur de « fonctions coûteuses » sera incrémenté pour chaque objet créé, à part pour la page courante ou pour un titre déjà chargé.

Si un nombre  est indiqué, un objet est créé pour la page ayant cet identifiant. Si aucune page n'a d'identifiant, retourne nil.

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

mw.title.makeTitle


Crée un objet Title avec le titre  dans l'espace de noms , avec les optionnels   et. peut être n'importe quelle clé de. Si le titre n'est pas valide, retourne ''nil'. Cette fonction est coûteuse dans les mêmes conditions que.

Notez que  crée un objet pour la page "Module:Foo" alors que   crée un objet pour la page "Template:Module:Foo".

Objet Title
Un objet Title a de nombreuses propriétés et méthodes, la plupart étant en lecture seule :


 * id : l'identifiant de la page. Vaut 0 si la page n'existe pas
 * interwiki : le préfixe interwiki ou vide si aucun
 * namespace : le numéro d'espace de noms
 * fragment : le fragment, ou vide. Peut être modifié
 * nsText : le nom 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 à.
 * baseText : si c'est une sous-page, le titre de la page dont on est la sous-page, sans préfixe. Sinon identique à.
 * subpageText : si c'est une sous-page, juste le nom de la sous-page. Sinon identique à.
 * canTalk : indique si la page peut avoir une page de discussion
 * exists : indique si la page existe. Alias pour fileExists pour les médias
 * fileExists : indique si la page existe.
 * 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 en: tous les Wikipédias sont considérés locaux mais pas les Wiktionnaires
 * isRedirect : indique si la page est une redirection
 * 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
 * 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
 * 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
 * contentModel : Le type de contenu pour ce titre, sous forme de chaîne. (Voir Manual:ContentHandler.)
 * basePageTitle : identique à.
 * rootPageTitle : identique à.
 * talkPageTitle : identique à , ou à nil si la page ne peut pas avoir de page de discussion.
 * subjectPageTitle : identique à.
 * subPageTitle( text ) : identique à.
 * partialUrl : retourne text encodé comme une URL.
 * fullUrl( query, proto ) : Retourne l'URL complète de la page (avec optionnellement un "query", une chaîne ou une table).  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 chaîne ou une table)
 * canonicalUrl( query ) : retourne l'URL canonique de la page (avec optionnellement un "query", une chaîne 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| ).

Les objets Title peuvent être comparés en utilisant les opérateurs relationnels. retourne.

mw.uri.encode
Encode la chaîne 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
Décode la chaîne "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
Encode la chaîne pour être utilisée en tant que fragment MediaWiki.

mw.uri.buildQueryString
Encode une table en tant que chaîne de requête. Les clés doivent être des chaînes. Les valeurs peuvent être des chaînes, des nombres, des séquences ou false.

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

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

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

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

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

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

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


 * protocol : chaîne 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 chaîne de la table de requête
 * relativePath : chemin, requête et fragment

retourne la chaîne de l'URI.

Les méthodes de l'objet URI sont :

mw.uri:parse
Analyse une chaîne dans l'objet URI courant. Tout champ spécifié dans la chaîne sera remplacé dans l'objet, les champs non spécifiés gardent leur ancienne valeur.

mw.uri:clone
Crée une copie de l'objet URI.

mw.uri:extend
Intègre la table parameters dans la table de requête de l'objet.

Librairie Ustring
La librairie ustring est une réimplémentation de la librairie standard string, avec la différence qu'elle peut opérer sur des caractères UTF-8.

La plupart des fonctions génèrent une erreur si la chaîne 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 chaîne, en octets.

mw.ustring.byte
Retourne les octets d'une chaîne. Identique à string.byte.

mw.ustring.byteoffset
Retourne la position en octets d'un caractère dans la chaîne. La valeur par défaut pour  et   est 1. peut être négatif, auquel cas c'est une position à partir de la fin.

Le caractère à  == 1 est le premier caractère qui commence à ou à partir de la position. Le caractère à  == 0 est le premier caractère qui commence à ou avant la position. Notez que ce peut être le même caractère. Des valeurs plus grandes ou plus petites de  sont calculées en relatif. (NDT : pas clair. À préciser)

mw.ustring.char
Similaire à string.char, mais les entiers retournés sont des points de codes Unicode et non des octets.

mw.ustring.codepoint
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
Similaire à string.find, mais le motif (pattern) est géré comme décrit dans motifs ustring et la position  est en caractères et non en octets.

mw.ustring.format
Identique à string.format. Les tailles et précisions pour les chaînes sont en octets et non en points de code Unicode.

mw.ustring.gcodepoint
Retourne trois valeurs pour itérer sur les points de code Unicode de la chaîne. vaut 1 par défaut et  vaut -1 par défaut. Ca sert à être utilisé par la forme itérateur de  :

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

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

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

mw.ustring.isutf8
Retourne vrai si la chaîne est en UTF-8 valide, faux sinon.

mw.ustring.len
Retourne la longueur de la chaîne en point de code Unicode ou nil si la chaîne n'est pas en UTF-8 valide.

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

mw.ustring.lower
Similaire à string.lower à part que la fonction suit le format Unicode.

Si la librairie Language est également chargée, ceci utilisera lc sur la langue courante à la place.

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

mw.ustring.rep
Identique à string.rep.

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

mw.ustring.toNFC
Convertit la chaîne en forme normalisée C. Retourne nil si la chaîne n'est pas valide en UTF-8.

mw.ustring.toNFD
Convertit la chaîne en forme normalisée D. Retourne nil si la chaîne n'est pas valide en UTF-8.

mw.ustring.upper
Similaire à string.upper à part que la fonction suit le format Unicode.

Si la librairie Language est également chargée, ceci utilisera uc sur la langue courante à la place.

Motifs ustring (pattern)
Les motifs dans les fonctions  utilisent la même syntaxe que celle des motifs de la librairie 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 :
 *   : représente tous les caractères de la catégorie "Lettre"
 *   : représente tous les caractères de la catégorie "Contrôle"
 *   : représente tous les caractères de la catégorie "Nombre décimal".
 *   : représente tous les caractères de la catégorie "Lettre minuscule".
 *   : représente tous les caractères de la catégorie "Ponctuation".
 *   : 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.
 *   : représente tous les caractères de la catégorie "Lettre majuscule"
 *   : représente tous les caractères de la catégorie "Lettre" ou "Nombre décimal"
 *   : 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, des motifs comme  , et des quantificateurs appliqués à des caractères multi-octets fonctionnent correctement. La capture vide capturera des positions en codes Unicode et non en octets.

Librairies chargeables
Ces librairies ne sont pas incluses par défaut, mais peuvent être chargées si besoin en utilisant.

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

bit32 = require( 'bit32' )

La librairie 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
Retourne le ET binaire 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
Retourne le complément binaire de.

bit32.bor
Retourne le OU binaire 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
Équivalent à

bit32.bxor
Retourne le OU EXCLUSIF binaire 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
Extrait  bits de , en commençant au bit. Accéder à des bits en dehors de l'intervalle 0 à 31 est une erreur.

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

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

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

bit32.lshift
Retourne le nombre  décalé de   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 2undefined.

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

bit32.rshift
Retourne le nombre  décalé de   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 2undefined.

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

bit32.arshift
Retourne le nombre  décalé de   bits vers la droite. Ceci est un décalage arithmétique : si  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
Retourne le nombre  décalé circulairement de   bits vers la gauche.

Notez que les rotations sont équivalentes modulo 32 : une rotation de 32 est identique à une rotation de 0, une rotation de 33 à une rotation de 1…

bit32.rrotate
Retourne le nombre  décalé circulairement de   bits vers la droite.

Notez que les rotations sont équivalentes modulo 32 : une rotation de 32 est identique à une rotation de 0, une rotation de 33 à une rotation de 1…

libraryUtil
Cette librairie contient des méthodes utiles pour implémenter des librairies Scribunto. Elle peut être chargée avec :

libraryUtil = require( 'libraryUtil' )

libraryUtil.checkType
Génère une erreur si  ne correspond pas à. De plus, aucune erreur n'est générée si  est nil et si   est vrai.

est le nom de la fonction qui appelle cette fonction, et  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.checkTypeForIndex
Génère une erreur si  ne correspond pas à code>expectType.

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

libraryUtil.checkTypeForNamedArg
Génère une erreur si  ne correspond pas à. De plus, aucune erreur n'est générée si  vaut nil et que   vaut true.

Cette fonction est un équivalent de la fonction  pour les méthodes appelées en utilisant la syntaxe des paramètres nommés.

libraryUtil.makeCheckSelfFunction
Ceci sert à implémenter des "méthodes" sur des tables destinées à être appelées avec la syntaxe. Il retourne une fonction qui peut être appelée « en haut » de ces méthodes avec le paramètre  et le nom de la méthode, et génère une erreur si l'objet   n'est pas.

Cette fonction est en général utilisé dans les constructeurs de fonctions de librairies :

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 librairies "bit" et "hex" de luabit peuvent être chargées avec :

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

Notez que la librairie bit32 contient les mêmes opérations que "luabit.bit", et que les opérations dans "luabit.hex" peuvent être réalisées en utilisant  et.

Le module "noki" n'est pas disponible car il n'est d'aucune utilité en Scribunto. Le module "utf8" n'est également pas disponible car redondant avec la librairie Ustring.

ustring
L'interface Lua native pour la librairie Ustring peut être chargée comme suit :

ustring = require( 'ustring' )

Dans tous les cas, la librairie Ustring devrait être utilisée à la place, car elle remplace de nombres fonctions plus lentes par des appels au code PHP.

Librairies d'extension
Les extensions MediaWiki suivantes fournissent des librairies Scribunto additionnelles :
 * Wikibase Client − voir Extension:Wikibase Client/Lua

Librairies Scribunto prévues
Ces librairies sont prévues ou sont en attente de validation.

Aucune librairie en attente de validation actuellement

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  et   (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:". Ne peut accéder au système de fichier local.

Fonctions et paquetages supprimés
Les paquetages suivants ont été presque supprimés. Seules les fonctions listées sont disponibles :
 * package.* : la gestion des systèmes de fichiers et la librairie 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 librairies 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
 * 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 debug
 * 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 entraînera un comportement indéterminé. Cela inclut (mais n'est pas limité à) la restitution de ces structures de données à partir du module appelé par  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 telles structures de données peuvent être utilisées librement dans Lua, y compris les valeurs de retour de modules chargés avec.

Écrire des librairies 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 librairies Scribunto, soit pour inclusion dans Scribunto, soit pour fournir une interface à leurs extensions.

Une librairie Scribunto comporte en général cinq parties :
 * la partie PHP de la librairie
 * la partie Lua de la librairie
 * la partie PHP des tests
 * la partie Lua des tests
 * la documentation.

Les librairies existantes sont un bon exemple de code.

Librairie
La partie PHP d'une librairie est une classe qui doit étendre. Voir la documentation de cette classe pour les détails d'implémentation. Dans l'extension Scribunto, ce fichier doit être placé dans, et un mapping ajouté à. D'autres extensions peuvent utiliser le hook. Dans les deux cas, la clé doit correspondre au nom du module ("mw.name" pour une librairie en Scribunto ou "mw.ext.name" pour une librairie d'extension).

La partie Lua de la librairie 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. Ce fichier ressemble en général à :

local object = {} local php function object.setupInterface( options ) -- Remove setup function object.setupInterface = nil -- Copy the PHP callbacks to a local variable, and remove the global php = mw_interface mw_interface = nil -- Do any other setup here -- Install into the mw global mw = mw or {} mw.ext = mw.ext or {} mw.ext.name = object -- Indicate that we're loaded package.loaded['mw.ext.name'] = object end return object

Le module dans  (chargez-le avec  ) contient diverses fonctions utiles pour réaliser cela.

Prenez soin de lancer les test cases Scribunto avec votre librairie chargée même si votre librairie ne fournit aucun test cases. Les tests standards contiennent des tests pour des choses comme des librairies ajoutant des variables globales indésirables.

Test cases
L'extension Scribunto contient une classe de base pour les tests,, qui effectue des tests avec les moteurs LuaSandbox et LuaStandalone. Les test cases de la librairie devraient étendre ces tests et ne devraient pas remplacer. Dans l'extension Scribunto, le test case doit être dans  et ajouté au tableau dans   (dans  ) ; les extensions doivent ajouter leur test case dans leur propre fonction   hook, probablement conditionné par le fait que   est fixé.

La plupart du temps, tout ce qui est nécessaire pour faire un test case 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  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 :, le nom du test  , et une chaîne qui est la sortie attendue du test.
 * run( n ) : fonction qui exécute le test  et retourne une chaîne.

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

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

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  et comment   est appelée. Les types sont :
 * Normal :  est une table des valeurs retournées, ou une chaîne si le test devrait générer une erreur.   est simplement appelée.
 * Iterator :  est une table de tables de valeurs retournées.   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 à.

Test cases 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 à   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   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. Et il est facile d'utiliser la première méthode si Scribunto est chargé car le hook  peut être écrit afin d'éviter de retourner le test Scribunto quand   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 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 test :

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

Documentation
Les modules pour Scribunto doivent inclure une documentation dans la section Librairies Scribunto (plus haut). Les librairies d'extension doivent inclure une documentation dans une sous-page de leur propre page d'extension, et lier vers cette documentation à un endroit approprié.

Voir aussi

 * Lua

Licence
Le manuel est inspiré du Lua 5.1 manuel de référence, qui est publié sous licence MIT. Ce travail dérivé doit donc être copié en conservant cette même licence.

Copyright © 1994–2012 Lua.org, PUC-Rio.

« ''Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

''THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.'' »