Unmodule est un morceau decode source écrit enLua. Son utilisation s'apparente à celle desmodèles (dont le langage de programmation est différent). Les modules se trouvent dans l'espace de noms dédiéModule:. Un module est invoqué par le code{{#invoke:nom_module|nom_fonction|arg1|arg2|…}} (et non{{nom_modèle|arg1|arg2|…}} comme les modèles).
Cette fonctionnalité est disponible depuis le 19 février 2013 sur Wikipédia en français.
Un module comporte une table locale quidoit être retournée (return) en fin de code. Toutes les fonctions exportées — c'est-à-dire utilisables à travers un#invoke — doivent être des éléments de cette table. Les fonctions exportées ne peuvent avoir qu'un paramètre déclaré,frame (voirl'objetframe), qui contient entre autres les paramètres passés lors de l'appel. D'autres fonctions (fonctions intermédiaires de traitement) peuvent être locales au module.
Un commentaire débute par deux tiretsdemi-cadratin :--. Une telle ligne (ou partie finale de ligne) permet d'expliquer le code, elle n'est pas interprétée.
Le titre de la page d'un module doit toujours commencer par « Module: » (contrairement auxmodèles). Dans la pageModule:Banane, le texte suivant a été écrit :
Note : le module suivant est le plus simple qu'il soit. Il ne possède aucun paramètre déclaré (frame).
-- Mon module très simple-- création de la "table" correspondant au module, elle est vide au départ d'où le {}localp={}-- vous pouvez l'appeler comme vous voulez, pas obligatoirement "p". Il faut toutefois-- utiliser le même nom de table lors de la déclaration des fonctions (p.hello() plus bas)-- Par ailleurs "p" est devenu une « norme » courante.---- définition de la fonction du module.-- « hello » est le nom qui sera indiqué lors de l'appel au module ({{#invoke:Banane|hello}}).-- Vous auriez pu appeler ce paramètre comme vous le souhaitez, pas nécessairement « hello »functionp.hello()-- Ici, on se contente de retourner un texte-- (donc pas de frame comme dans exemple [[Module:Hello]])return"Hello, world!"-- ce qui est retourné est entre guillemets (c'est un texte)end-- et c'est tout-- obligatoire : on retourne la table du module (qui contient les fonctions)returnp
Dans une autre page qui ne soit pas dans l'espace de noms module, par exempleModèle:Bac à sable, écrivez :
{{#invoke:Banane|hello}}Note : si le module s'était appelé« truc », il aurait fallu écrire{{#invoke:truc|hello}}.
Ceci va appeler la fonction « hello » exportée par ce module. Le code{{#invoke:Banane|hello}} sera remplacé par le texte que cette fonction retourne, dans cet exemple « Hello, world! ».
C'est généralement une bonne idée d'« invoquer » un code Lua depuis une page del'espace de noms« modèle: » plutôt que directement dans les pages destinées au grand public (articles,PdD, projet, , etc.). De cette façon, la syntaxe des pages courantes est constante, que le code ait été écrit en Lua ou en wikicode. Ainsi cela évite d'introduire une nouvelle syntaxe complexe dans ces pages-ci.
Avecl'objetframe et un argument
Dans la pageModule:Hello, le texte suivant a été écrit :
-- test Lua-- utiliser {{#invoke:hello|helloworld}}localp={}functionp.helloworld()return'Hello World! Welcome to Lua!'end-- utiliser {{#invoke:hello|hello|Monsieur X}}functionp.hello(frame)-- remarquez le framereturn'Hello '..frame.args[1]..'!'endreturnp
{{#invoke:hello|helloworld}}→ Hello World! Welcome to Lua!
{{#invoke:hello|hello|Monsieur X}} →Hello Monsieur X!
L'objetframe correspond à l'appelant (l'endroit où le#invoke est fait) et contient entre autres les paramètres passés lors de l'appel, ici « Monsieur X ».
Avecl'objetframe et les arguments
VoirModule:BananesArgs pour une explication par l'exemple des arguments.
Voir aussiModule:Module Factorielle.
Dans la pageModule:ExempleParams, le texte suivant a été écrit :
-- Illustration du passage des paramètres dans les modules Lua-- utilisation des itérations sur ipairs() et pairs()localp={}functionp.imprime_les_parametres(params)localx=''localindex,valeurlocalcle,valx=x.."'''Paramètres non nommés'''\n"forindex,valeurinipairs(params.args)dox=x..'* param['..index..'] = '..valeur..'\n'endx=x.."<br/>'''Paramètres non nommés et nommés'''\n"forcle,valinpairs(params.args)dox=x..'* param{'..cle..'} = '..val..'\n'endreturnxendreturnp
Voir les explications dansModule:ExempleParams.
Remarquer :
Les motivations ayant conduit à l'intégration de Lua dansMediaWiki (le logiciel qui fait tourner Wikipédia) sont :
Un module devrait être utilisé lorsque le coût d'exécution d'un modèle est élevé. Le coût d'exécution d'un modèle est difficile à évaluer mais est proportionnel au nombre d'appels à des sous-modèles etparser-functions.
Un module devrait être également utilisé lorsque la complexité d'un modèle rend délicate sa compréhension et sa modification.
Un module devrait enfin être utilisé chaque fois que les fonctionnalités souhaitées ne peuvent être réalisées avec lesparser-functions existantes.
Se référer aux documents suivants :
La documentation du modulenom_module se place dans lasous-pagemodule:nom_module/Documentation.
Lorsqu'on lit une page de module ne possédant pas de documentation, un texte en début de page l'indique et fournit un lien permettant de créer directement la page de documentation. L'utilisation de ce lien pré-charge un modèle-guide de documentation pour définir les paramètres passés au modèle au cours de la confection de l'article avec l'éditeur visuel; Ce guide est en français, la séquence est logique et ne produit pas d'erreur de constitution de la table contenant la documentation.
Suivez le modèle pré-chargé de documentation. Il faut décrire chaque fonction exportée : son nom, son rôle, les paramètres (nommés et non nommés) attendus. Il est aussi conseillé de documenter les dépendances (autres modules utilisés, bibliothèques…) ainsi que les fonctions internes (rôle, paramètres…).
La documentation d'un module est une documentation d'utilisation, destinée aux personnes voulant utiliser le module, mais c'est aussi une documentation technique, destinée aux personnes voulant faire de la maintenance. Le ou les modèles qui utilisent ce module ont, eux, leur propre documentation d'utilisation, destinée aux personnes voulant utiliser ce(s) modèle(s) avec l'éditeur visuel ou l'éditeur de wikicode, basculables de l'un vers l'autre.
Note :Il ne faut pas insérer dans cette documentation le modèle{{Documentation}}. En effet l'insertion des éléments de documentation s'effectue directement par MediaWiki lors de la visualisation des pages.
On peut utiliser un module directement par l'appel à#invoke :
{{#invoke:nom-du-module|nom_de_la_fonction|paramètres…}}
Sans paramètre, cela donne :
{{#invoke:nom-du-module|nom_de_la_fonction}}
On peut aussi utiliser un module à travers un modèle. Dans ce cas le rédacteur fait appel à un modèle comme il a l'habitude de le faire, mais le modèle fait appel à une ou plusieurs fonctions dans un ou plusieurs modules avec la syntaxe#invoke.
Par exemple, dans un modèle :{{#invoke:nom-du-module|nom_de_la_fonction|{{{1}}}|{{{2}}}|paramètre 1={{{3|valeur par défaut}}}|paramètre 2=fr|…}}
Cette seconde approche doit être préférée à l'appel direct pour plusieurs raisons :
#invoke depuis l'espace encyclopédique.#invoke). Gérer les deux cas complique la programmation des modules et peut conduire à des effets indésirables.