Loading AI tools
De Wikipédia, l'encyclopédie libre
Un module est un morceau de code source écrit en Lua. Son utilisation s'apparente à celle des modè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 qui doit ê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 (voir l'objet frame), 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 tirets demi-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 aux modèles). Dans la page Module: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 {}
local p = {} -- 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 »
function p.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)
return p
Dans une autre page qui ne soit pas dans l'espace de noms module, par exemple Modè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 de l'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.
Avec l'objet frame et un argument
Dans la page Module:Hello, le texte suivant a été écrit :
-- test Lua
-- utiliser {{#invoke:hello|helloworld}}
local p = {}
function p.helloworld()
return 'Hello World! Welcome to Lua!'
end
-- utiliser {{#invoke:hello|hello|Monsieur X}}
function p.hello(frame) -- remarquez le frame
return 'Hello ' .. frame.args[1] .. '!'
end
return p
{{#invoke:hello|helloworld}}
→ Hello World! Welcome to Lua!
{{#invoke:hello|hello|Monsieur X}}
→
Hello Monsieur X!
L'objet frame 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 ».
Avec l'objet frame et les arguments
Voir Module:BananesArgs pour une explication par l'exemple des arguments.
Voir aussi Module:Module Factorielle.
Dans la page Module: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()
local p = {}
function p.imprime_les_parametres(params)
local x = ''
local index, valeur
local cle, val
x = x.."'''Paramètres non nommés'''\n"
for index,valeur in ipairs(params.args) do
x = x..'* param['..index..'] = '..valeur..'\n'
end
x = x.."<br/>'''Paramètres non nommés et nommés'''\n"
for cle,val in pairs(params.args) do
x = x..'* param{'..cle..'} = '..val..'\n'
end
return x
end
return p
Voir les explications dans Module:ExempleParams.
Remarquer :
Les motivations ayant conduit à l'intégration de Lua dans MediaWiki (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 et parser-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 les parser-functions existantes.
Se référer aux documents suivants :
La documentation du module nom_module
se place dans la sous-page module: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.