MechsploWikiSysop: 1 revision imported

2025-09-02T02:50:13Z

1 revision imported

← Older revision	Revision as of 22:50, 1 September 2025
(No difference)

mw>Wladek92: Created page with "Ceci a été un problème avec les modules qui utilisent $1 pour détecter s'il faut utiliser les arguments à partir du ''frame'' ou du ''frame parent'', car ces modules traitent automatiquement chaque argument disponible."

2025-01-20T18:13:34Z

Created page with "Ceci a été un problème avec les modules qui utilisent $1 pour détecter s'il faut utiliser les arguments à partir du ''frame'' ou du ''frame parent'', car ces modules traitent automatiquement chaque argument disponible."

New page

<noinclude>{{#ifeq:{{SUBPAGENAME}}|doc||{{Documentation subpage}}}}<languages /></noinclude>{{#switch:
| =
<includeonly>{{Languages|Module:Arguments/doc}}</includeonly>

{{Shared Template Warning|Module:Arguments|Module:Arguments}}
{{Used in system}}
{{Module rating|release}}
{{Module rating|protected}}

Ce module facilite le traitement des arguments reçus de {{Magic word|#invoke|...|ext=Scribunto|code=1|nowrap=1}}.
Il s'agit d'un méta-module, destiné à être utilisé par d'autres modules; il ne doit pas être appelé directement à partir de {{tlc|<nowiki>#invoke:...</nowiki>}}.
Ses fonctionnalités comprennent :

* la séparation facile des arguments et la suppression des arguments vides.
* les arguments peuvent venir à la fois de l'environnement (''frame'') courant et de l'environnement parent (informations plus détailées ci-dessous).
* vous pouvez passer les arguments directement à partir d'un autre module Lua ou de la console de débogage.
* les arguments sont récupérés selon les besoins, ce qui permet d'éviter (certains) problèmes avec les balises {{xtag|ref}}.
* la plupart des fonctionnalités peuvent être personnalisées.


== Utilisation de base ==
Vous devez d'abord charger le module.
Il contient une fonction nommée <code>getArgs</code>.

<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs
</syntaxhighlight>

Pour un scénario élémentaire, vous pouvez utiliser <code>getArgs</code> dans votre fonction principale.
La variable <code>args</code> est une table contenant les arguments de {{tlc|<nowiki>#invoke:...</nowiki>}}
(voir les détails ci-dessous).

<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs
local p = {}

function p.main(frame)
local args = getArgs(frame)
-- Placer ici le code principal du module.
end

return p
</syntaxhighlight>

Néanmoins, il est recommandé d'utiliser une fonction juste pour traiter les arguments de {{tlc|<nowiki>#invoke:...</nowiki>}}.
Cela signifie que si quelqu'un appelle votre module à partir d'un autre module Lua, vous n'avez pas besoin d'avoir un objet ''frame'' disponible, ce qui améliore les performances.

<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs
local p = {}

function p.main(frame)
local args = getArgs(frame)
return p._main(args)
end

function p._main(args)
-- Placer ici le code principal du module.
end

return p
</syntaxhighlight>

Si vous voulez que plusieurs fonctions utilisent les arguments, et qu'ils soient accessibles à partir de {{tlc|<nowiki>#invoke:...</nowiki>}}, vous pouvez utiliser une fonction conteneur (''wrapper'').

<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs

local p = {}

local function makeInvokeFunc(funcName)
return function (frame)
local args = getArgs(frame)
return p[funcName](args)
end
end

p.func1 = makeInvokeFunc('_func1')

function p._func1(args)
-- placer ici le code de la première fonction
end

p.func2 = makeInvokeFunc('_func2')

function p._func2(args)
-- placer ici le code de la seconde fonction
end

return p
</syntaxhighlight>

=== Options ===
Les options suivantes sont disponibles.
Elles sont expliquées dans les sections ci-dessous.

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
trim = false,
removeBlanks = false,
valueFunc = function (key, value)
-- code pour traiter un argument
end,
frameOnly = true,
parentOnly = true,
parentFirst = true,
wrappers = {
'Template:A wrapper template',
'Template:Another wrapper template'
},
readOnly = true,
noOverwrite = true
})
</syntaxhighlight>


=== Séparation et suppression des caractères espace ===
Les arguments vides posent souvent problème aux nouveaux codeurs dans la conversion des modèles MediaWiki en Lua.
Dans la syntaxe du modèle, les chaînes vides et les chaînées constituées uniquement d'espaces sont considérées comme <code>false</code>.
Cependant, en Lua, les chaînes vides et les chaînées constituées d'espaces sont considérées comme <code>true</code>.
Cela signifie que si vous ne faites pas attention à ces arguments lorsque vous écrivez vos modules Lua, vous pouvez traiter quelque chose comme <code>true</code> alors qu'il devrait être traité comme <code>false</code>.
Pour éviter cela, ce module supprime par défaut tous les arguments vides.

De même, le caractère espace (blanc) peut causer des problèmes si vous utilisez des arguments positionnels.
Bien que le caractère blanc soit supprimé pour les arguments nommés venant de {{tlc|<nowiki>#invoke:...</nowiki>}}, il est conservé pour les arguments positionnels.
La plupart du temps, cet espace blanc supplémentaire n'est pas souhaité, donc ce module le supprime par défaut.

Cependant, parfois vous voulez utiliser des arguments vides en entrée, et parfois vous voulez garder l'espace blanc supplémentaire.
Cela peut obliger à convertir certains modèles exactement comme ils ont été écrits.
Si vous voulez faire cela, vous pouvez initialiser les arguments <code>trim</code> et <code>removeBlanks</code> à <code>false</code>.

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
trim = false,
removeBlanks = false
})
</syntaxhighlight>


=== Format personnalisé des arguments ===
Parfois, vous voulez supprimer certains arguments vides mais pas les autres, ou peut-être vous voulez mettre tous les arguments positionnels en minuscules.
Pour faire des choses similaires, utilisez l'option <code>valueFunc</code>.
L'entrée de cette option doit être une fonction qui prend deux paramètres <code>key</code> et <code>value</code>, et qui renvoie une seule valeur.
Cette valeur est celle que vous obtenez lorsque vous accédez au champ <code>key</code> de la table <code>args</code>.

'''Exemple 1 :'''
Cette fonction préserve l'espace blanc pour le premier argument positionnel, mais le supprime pour tous les autres arguments; les arguments vides restants sont supprimés.

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
valueFunc = function (key, value)
if key == 1 then
return value
elseif value then
value = mw.text.trim(value)
if value ~= '' then
return value
end
end
return nil
end
})
</syntaxhighlight>

'''Exemple 2 :'''
Cette fonction supprime les arguments vides et convertit tous les arguments en minuscules, mais n'élimine pas l'espace blanc des paramètres positionnels.

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
valueFunc = function (key, value)
if not value then
return nil
end
value = mw.ustring.lower(value)
if mw.ustring.find(value, '%S') then
return value
end
return nil
end
})
</syntaxhighlight>

{{Note|text=
Les fonctions ci-dessus échouent quand l'entrée fournie n'est pas du type <code>string</code> ou <code>nil</code>.
Cela pourrait être le cas si vous utilisez la fonction <code>getArgs</code> dans la fonction principale de votre module, et que cette fonction est appelée par un autre module Lua.
Dans ce cas, vous devez vérifier le type de l'entrée.
Ce n'est pas un problème si vous utilisez une fonction spécialement pour les arguments de {{tlc|<nowiki>#invoke:...</nowiki>}} (par exemple quand vous avez des fonctions <code>p.main</code> et <code>p._main</code> ou similaires).
}}

{{Collapse top|1=Exemples 1 et 2 avec le contrôle de type}}
Exemple 1 :
<syntaxhighlight lang="lua">
local args = getArgs(frame, {
valueFunc = function (key, value)
if key == 1 then
return value
elseif type(value) == 'string' then
value = mw.text.trim(value)
if value ~= '' then
return value
else
return nil
end
else
return value
end
end
})
</syntaxhighlight>

Exemple 2 :
<syntaxhighlight lang="lua">
local args = getArgs(frame, {
valueFunc = function (key, value)
if type(value) == 'string' then
value = mw.ustring.lower(value)
if mw.ustring.find(value, '%S') then
return value
else
return nil
end
else
return value
end
end
})
</syntaxhighlight>
{{Collapse bottom}}

Veuillez également noter que la fonction <code>valueFunc</code> est appelée plus ou moins chaque fois qu'un argument est demandé à partir de la table <code>args</code>, donc si vous vous souciez des performances vérifiez que votre code reste toujours efficace.


=== Environnement et environnement parent ===

Les arguments de la table <code>args</code> peuvent venir à la fois de la ''frame'' actuelle et de la ''frame'' parente.
Pour comprendre ce que cela signifie, prenons un exemple.
Supposons que nous disposons d'un module appelé <code>Module:ExampleArgs</code>.
Ce module imprime les deux premiers arguments positionnels qu'il a reçus.

{{Collapse top|1=code de Module:ExampleArgs}}
<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs
local p = {}

function p.main(frame)
local args = getArgs(frame)
return p._main(args)
end

function p._main(args)
local first = args[1] or ''
local second = args[2] or ''
return first .. ' ' .. second
end

return p
</syntaxhighlight>
{{Collapse bottom}}

<code>Module:ExampleArgs</code> est ensuite appelé par <code>Template:ExampleArgs</code> qui contient le code <code><nowiki>{{#invoke:ExampleArgs|main|firstInvokeArg}}</nowiki></code>.
Ceci produit le résultat "firstInvokeArg".

Maintenant si on devait appeler <code>Template:ExampleArgs</code>, on aurait ceci :

{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} Code
! style="width: 40%;" {{!}} Résultat
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg secondTemplateArg
{{!)}}

Il existe trois options qui vous permettent de modifier ce comportement : <code>frameOnly</code>, <code>parentOnly</code> et <code>parentFirst</code>.
Si vous définissez <code>frameOnly</code> alors seulement les arguments passés du ''frame courant'' seront acceptés; si vous définissez <code>parentOnly</code> alors seulement les arguments passés du ''frame parent'' seront acceptés. Et si vous définirez <code>parentFirst</code> alors les arguments seront passés à la fois du frame actuel et de celui du parent, mais ce dernier aura la priorité sur le frame actuel.
Voici les résultats en termes de <code>Template:ExampleArgs</code> :

<dl>
<dt><code>frameOnly</code></dt>
<dd>
{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} Code
! style="width: 40%;" {{!}} Résultat
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg
{{!)}}
</dd>

<dt><code>parentOnly</code></dt>
<dd>
{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} Code
! style="width: 40%;" {{!}} Résultat
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}}
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg secondTemplateArg
{{!)}}
</dd>

<dt><code>parentFirst</code></dt>
<dd>
{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} Code
! style="width: 40%;" {{!}} Résultat
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg secondTemplateArg
{{!)}}
</dd>
</dl>

{{Note|text=
{{Ordered list
|1=
Si vous définissez les options <code>frameOnly</code> et <code>parentOnly</code>, le module ne trouvera aucun argument à partir de {{tlc|<nowiki>#invoke:...</nowiki>}}.
Ce n'est pas forcément ce que vous souhaitez.
|2=
Dans certaines situations, un cadre parent peut ne pas être disponible, par exemple si <code>getArgs</code> passe le cadre parent à la place du cadre actuel.
Dans ce cas, seuls les arguments du frame seront utilisés (sauf si <code>parentOnly</code> est initialisé, dans ce cas aucun argument ne sera utilisé) et les options <code>parentFirst</code> et <code>frameOnly</code> n'auront aucun effet.
}}
}}


=== Conteneurs ===

L'option <code>wrappers</code> est utilisée pour spécifier un nombre limité de ''modèles utilisés comme conteneurs'', c'est à dire des modèles qui ne font qu'appeler un module.
Si ce module détecte qu'il est appelé à partir d'un modèle conteneur, il vérifie les arguments dans la ''frame'' parente; sinon il vérifie les arguements dans la ''frame'' fournie à <code>getArgs</code>.
Cela permet d'appeler les modules soit par {{tlc|<nowiki>#invoke:...</nowiki>}} soit par un modèle conteneur sans la perte de performance associée à la vérification de la ''frame'' et de celle du parent dans chaque recherche d'argument.

Par exemple le seul contenu de {{tlx|Navbox}} est <code><nowiki>{{#invoke:Navbox|navbox}}</nowiki></code> (en excluant le contenu entre les balises {{tag|noinclude}}).
Il n'est pas utile de vérifier les arguments transmis directement à la déclaration {{tlc|<nowiki>#invoke:...</nowiki>}} pour ce modèle, car aucun argument n'y sera jamais spécifié.
Nous pouvons éviter de vérifier les arguments passés à {{tlc|<nowiki>#invoke:...</nowiki>}} en utilisant l'option <code>parentOnly</code> , mais si nous le faisons, {{tlc|<nowiki>#invoke:...</nowiki>}} ne fonctionnera pas non plus depuis les autres pages.
Si c'était le cas, alors {{tmpl|0={{para|text|$1}}|Quelque mots}} dans le code {{tmpl|0={{tlc|<nowiki>#invoke:Navbox</nowiki>|navbox|3=text=$1}}|Quelque mots}} serait complètement ignoré, quelque soit la page où il a été utilisé.
En utilisant l'option <code>wrappers</code> pour indiquer que [[Template:Navbox]] est un conteneur, nous pouvons faire que {{tmpl|0={{tlc|<nowiki>#invoke:Navbox</nowiki>|main|3=text=$1}}|Quelque mots}} fonctionne sur la plupart des pages, tout en ne nécessitant pas que le module vérifie les arguments sur la page [[Template:Navbox]] lui-même.

Les conteneurs peuvent être spécifiés par des chaînes ou des tableaux de chaînes.

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
wrappers = 'Template:Wrapper template'
})
</syntaxhighlight>

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
wrappers = {
'Template:Wrapper 1',
'Template:Wrapper 2',
-- Vous pouvez ajouter ici un nombre quelconque de conteneurs.
}
})
</syntaxhighlight>

{{Note|text=
{{Ordered list
|1=
Le module détecte automatiquement si l'appel vient de la sous-page <code>/sandbox</code> d'un modèle de conteneur, il n'est donc pas nécessaire de spécifier explicitement des pages de bac à sable.
|2=
L'option <code>wrappers</code> modifie effectivement les valeurs par défaut des options <code>frameOnly</code> et <code>parentOnly</code>.
Si par exemple, <code>parentOnly</code> était défini explicitement à <code>false</code> avec <code>wrappers</code> initialisé, les appels via les modèles conteneur entraîneraient à la fois le chargement des arguments du ''frame'' et de ceux des parents, alors que les appels sans le modèle conteneur entraîneraient le chargement uniquement des arguments du ''frame''.
|3=
Si l'option <code>wrappers</code> est définie et qu'aucun ''frame parent'' n'est disponible, le module récupèrera toujours les arguments du ''frame'' passé à <code>getArgs</code>.
}}
}}

=== Ecrire dans la table <code>args</code> ===
Il est quelques fois nécessaire d'écrire de nouvelles valeurs dans la table <code>args</code>.
Ceci est possible avec les valeurs par défaut de ce module.
(Néanmoins gardez à l'esprit qu'au niveau codage, il vaut mieux créer une nouvelle table avec les nouvelles valeurs et copier les arguments de la table de <code>args</code> selon les besoins).

<syntaxhighlight lang="lua">
args.foo = 'valeur quelconque'
</syntaxhighlight>

Vous pouvez modifier ce comportement avec les options <code>readOnly</code> et <code>noOverwrite</code>.
Si <code>readOnly</code> est initialisé, il n'est plus du tout possible d'écrire des valeurs dans la table <code>args</code>.
Si <code>noOverwrite</code> est défini, il est possible d'ajouter de nouvelles valeurs à la table, mais il n'est pas possible d'ajouter une valeur si elle vient réécraser un argument passé à partir de {{tlc|<nowiki>#invoke:...</nowiki>}}.


=== Balises ref ===
Cemodule utilise les [[mw:Special:MyLanguage/Extension:Scribunto/Lua reference manual#Metatables|métatables]] pour récupérer les arguments de {{tlc|<nowiki>#invoke:...</nowiki>}}.
Cela permet d'accéder aux arguments du frame et à ceux du parent sans passer par la fonction <code>pairs()</code>.
Cela peut vous aider si votre module a reçu des balises {{xtag|ref}} en entrée.

Dès que les balises {{xtag|ref}} sont accédées par Lua, elles sont traitées par le logiciel MediaWiki et la référence apparaîtra dans la liste des références au bas de l'article.
Si votre module continue à omettre la balise de référence de la sortie, vous finirez par avoir une référence fantôme - une référence qui apparaît dans la liste des références, mais aucun numéro ne la relie.
Ceci a été un problème avec les modules qui utilisent <code>pairs()</code> pour détecter s'il faut utiliser les arguments à partir du ''frame'' ou du ''frame parent'', car ces modules traitent automatiquement chaque argument disponible.

Ce module résoud le problème en permettant l'accès à la fois aux arguments du ''frame'' et à celui du parent, tout en les récupérant quand lorsque c'est nécessaire.
Cependant le problème se produira toujours si vous utilisez <code>pairs(args)</code> ailleurs dans votre module.


=== Limitations connues ===
L'utilisation des métatables a aussi ses inconvénients.
La plupart des outils Lua sur les tableaux usuels ne fonctionneront pas correctement sur la table <code>args</code>, y compris l'opérateur <code>#</code>, la fonction <code>next()</code>, et les fonctions de la bibliothèque <code>table</code>.
Si l'utilisation de ces éléments est importante pour votre module, vous devriez utiliser votre propre fonction de traitement des arguments au lieu de ce module.

== Tests ==
{{ModuleQuality}}
<includeonly>{{Sandbox other||

[[Category:Lua metamodules{{#translation:}}]]
}}</includeonly><noinclude>
[[Category:Module documentation pages{{#translation:}}]]
</noinclude>
| #default=
{{#invoke:Template translation|renderTranslatedTemplate|template=Module:Arguments/doc|noshift=1|uselang={{int:lang}}}}
}}

Module:Arguments/doc/fr - Revision history

MechsploWikiSysop: 1 revision imported

mw>Wladek92: Created page with "Ceci a été un problème avec les modules qui utilisent $1 pour détecter s'il faut utiliser les arguments à partir du ''frame'' ou du ''frame parent'', car ces modules traitent automatiquement chaque argument disponible."