Projet:Scribunto/Guide/Structure Lua

Il est important de comprendre que comme pour les modèles l'appel à un module est remplacé par le texte retourné par le module.
Cela veut donc dire que le module (en fait la fonction appelée dans le module) doit retourner un texte.

Ce texte peut comporter tous les éléments de structuration wiki habituels (mise en gras, italiques, références, tableaux, code HTML, …) ainsi bien sûr que du texte pur.
Attention : mediawiki considère que le texte retourné est déjà « évalué ». En particulier la présence d'un appel de modèle ne sera pas traité.
Par exemple si je retourne ceci dans mon module :

(...)
  return "Ici j'appelle un modèle : {{MonModele}}"
end

je n'obtiendrai pas l'affichage du texte "Ici j'appelle un modèle :" suivi de ce que fait le modèle "MonModele", mais j'obtiendrai réellement le texte "Ici j'appelle un modèle : {{MonModele}}".

S'il est nécessaire d'évaluer un modèle (c'est en général le cas) il faut faire appel à une fonction particulière du paramètre frame (le paramètre que reçoit la fonction appelée par un modèle) : preprocess. Cette fonction permet de "résoudre" les inclusions. Exemple :

(...)
  return frame:preprocess("Ici j'appelle un modèle : {{MonModele}}")
end

Notez que vous pouvez n'appeler cette fonction que sur les parties qui en ont besoin :

(...)
  return "Ici j'appelle un modèle : " .. frame:preprocess("{{MonModele}}")
end

Lorsqu'on génère une sortie longue et complexe c'est plus économique (en ressources sur les serveurs) de ne faire le preprocess que sur les éléments en ayant réellement besoin. Évitez d'utiliser cette fonction quand elle n'est pas nécessaire.

Note : attention, c'est bien frame:preprocess() (avec comme séparateur les deux-points et non un simple point comme pour les appels classiques de fonctions). L'explication dépasse le cadre de ce texte.
Note bis : c'est quoi qu'il en soit une mauvaise idée que d'utiliser preprocess. En effet le but de Lua est d'éviter les appels de modèles qui sont beaucoup plus coûteux pour les serveurs. Il est donc dommage de re-créer ce comportement coûteux à l'intérieur d'un module. Ce peut être toutefois nécessaire dans certains cas.

Code minimal d'un module

Une ligne de commentaire débute par les deux tirets demi-cadratin  : « -- ». Une telle ligne permet d'expliquer le code, elle n'est pas interprétée.

Le module le plus simple qu'on puisse écrire est le suivant :

-- mon module très simple

-- création de la "table" (vide au départ, d'où le {}) correspondant au module
local z = {} -- vous pouvez l'appeler comme vous voulez, pas obligatoirement "z"

-- définition de la fonction du module. C'est le nom qui sera passé lors de l'appel
--  au module : {{#invoke|le-nom-de-mon-module|le_nom_de_la_fonction}}
function z.ma_fonction(frame)  -- toujours le paramètre frame
  -- on se contente de retourner un texte
  return "Ceci est la sortie de la fonction 'ma_fonction' de mon module."
end -- et c'est tout
-- obligatoire : on retourne la table du module (qui contient les fonctions)
return z

Dans cet exemple le module serait appelé Module:le-nom-de-mon-module

Le modèle servant à appeler ce module serait alors :

{{#invoke:le-nom-de-mon-module|ma_fonction}}<noinclude>La documentation et autres…</noinclude>

Remarques

On trouve déjà dans ces exemples des éléments de code qui n'ont pas encore été détaillés (comme return, les paramètres, certains opérateurs…). Voir plus loin leur description.