Module:Arguments/doc/fr

Attention:

Cette page est partagée entre plusieurs wikis. Toutes les modifications apportées à cette page seront automatiquement copiées sur tous les wikis répertoriés dans la barre de gauche. Merci de nous aider à traduire cette page.

Ce module facilite le traitement des arguments reçus de {{#invoke:...}}. Il s'agit d'un méta-module, destiné à être utilisé par d'autres modules; il ne doit pas être appelé directement à partir de {{#invoke:...}}. 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 ‎<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 getArgs.

local getArgs = require('Module:Arguments').getArgs

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

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

Néanmoins, il est recommandé d'utiliser une fonction juste pour traiter les arguments de {{#invoke:...}}. 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.

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

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

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

Options

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

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
})

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 false. Cependant, en Lua, les chaînes vides et les chaînées constituées d'espaces sont considérées comme true. Cela signifie que si vous ne faites pas attention à ces arguments lorsque vous écrivez vos modules Lua, vous pouvez traiter quelque chose comme true alors qu'il devrait être traité comme false. 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 {{#invoke:...}}, 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 trim et removeBlanks à false.

local args = getArgs(frame, {
	trim = false,
	removeBlanks = false
})

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 valueFunc. L'entrée de cette option doit être une fonction qui prend deux paramètres key et value, et qui renvoie une seule valeur. Cette valeur est celle que vous obtenez lorsque vous accédez au champ key de la table args.

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.

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
})

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.

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
})

Les fonctions ci-dessus échouent quand l'entrée fournie n'est pas du type string ou nil.

Cela pourrait être le cas si vous utilisez la fonction getArgs 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 {{#invoke:...}} (par exemple quand vous avez des fonctions p.main et p._main ou similaires).

Exemples 1 et 2 avec le contrôle de type

Exemple 1 : 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 }) Exemple 2 : 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 })

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

Environnement et environnement parent

Les arguments de la table args 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é Module:ExampleArgs. Ce module imprime les deux premiers arguments positionnels qu'il a reçus.

code de Module:ExampleArgs
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

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

Maintenant si on devait appeler Template:ExampleArgs, on aurait ceci :

Code	Résultat
{{ExampleArgs}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstInvokeArg secondTemplateArg

Il existe trois options qui vous permettent de modifier ce comportement : frameOnly, parentOnly et parentFirst. If you set frameOnly then only arguments passed from the current frame will be accepted; if you set parentOnly then only arguments passed from the parent frame will be accepted; and if you set parentFirst then arguments will be passed from both the current and parent frames, but the parent frame will have priority over the current frame. Voici les résultats en termes de Template:ExampleArgs :

frameOnly

Code	Résultat
{{ExampleArgs}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstInvokeArg

parentOnly

Code	Résultat
{{ExampleArgs}}
{{ExampleArgs|firstTemplateArg}}	firstTemplateArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstTemplateArg secondTemplateArg

parentFirst

Code	Résultat
{{ExampleArgs}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg}}	firstTemplateArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstTemplateArg secondTemplateArg

1. Si vous définissez les options frameOnly et parentOnly, le module ne trouvera aucun argument à partir de {{#invoke:...}}. 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 getArgs passe le cadre parent à la place du cadre actuel. In this case, only the frame arguments will be used (unless parentOnly is set, in which case no arguments will be used) and the parentFirst and frameOnly options will have no effect.

Conteneurs

The wrappers option is used to specify a limited number of templates as wrapper templates, that is, templates whose only purpose is to call a 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 à getArgs. This allows modules to be called by either {{#invoke:...}} or through a wrapper template without the loss of performance associated with having to check both the frame and the parent frame for each argument lookup.

Par exemple le seul contenu de {{Navbox}} est {{#invoke:Navbox|navbox}} (en excluant le contenu entre les balises ‎<noinclude>...‎</noinclude>). There is no point in checking the arguments passed directly to the {{#invoke:...}} statement for this template, as no arguments will ever be specified there. We can avoid checking arguments passed to {{#invoke:...}} by using the parentOnly option, but if we do this then {{#invoke:...}} will not work from other pages either. If this were the case, then |text=Some text in the code {{#invoke:Navbox|navbox|text=Some text}} would be ignored completely, no matter what page it was used from. By using the wrappers option to specify Template:Navbox as a wrapper, we can make {{#invoke:Navbox|main|text=Some text}} work from most pages, while still not requiring that the module check for arguments on the Template:Navbox page itself.

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

local args = getArgs(frame, {
	wrappers = 'Template:Wrapper template'
})

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

1. Le module détecte automatiquement si l'appel vient de la sous-page /sandbox 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 wrappers modifie effectivement les valeurs par défaut des options frameOnly et parentOnly. If, for example, parentOnly were explicitly set to false with wrappers set, calls via wrapper templates would result in both frame and parent arguments being loaded, though calls not via wrapper templates would result in only frame arguments being loaded.
3. If the wrappers option is set and no parent frame is available, the module will always get the arguments from the frame passed to getArgs.

Ecrire dans la table args

Il est quelques fois nécessaire d'écrire de nouvelles valeurs dans la table args. Ceci est possible avec les valeurs par défaut de ce module. (However, bear in mind that it is usually better coding style to create a new table with your new values and copy arguments from the args table as needed.)

args.foo = 'valeur quelconque'

Vous pouvez modifier ce comportement avec les options readOnly et noOverwrite. Si readOnly est initialisé, il n'est plus du tout possible d'écrire des valeurs dans la table args. If noOverwrite is set, then it is possible to add new values to the table, but it is not possible to add a value if it would overwrite any arguments that are passed from {{#invoke:...}}.

Balises ref

Cemodule utilise les métatables pour récupérer les arguments de {{#invoke:...}}. This allows access to both the frame arguments and the parent frame arguments without using the pairs() function. This can help if your module might be passed ‎<ref> tags as input.

As soon as ‎<ref> tags are accessed from Lua, they are processed by the MediaWiki software and the reference will appear in the reference list at the bottom of the article. If your module proceeds to omit the reference tag from the output, you will end up with a phantom reference - a reference that appears in the reference list, but no number that links to it. This has been a problem with modules that use pairs() to detect whether to use the arguments from the frame or the parent frame, as those modules automatically process every available argument.

This module solves this problem by allowing access to both frame and parent frame arguments, while still only fetching those arguments when it is necessary. Cependant le problème se produira toujours si vous utilisez pairs(args) 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 args, y compris l'opérateur #, la fonction next(), et les fonctions de la bibliothèque table. If using these is important for your module, you should use your own argument processing function instead of this module.

Tests

Test Status

Module:Arguments	success: 51, error: 0, skipped: 0
Module:Arguments/sandbox	success: 51, error: 0, skipped: 0

• See test cases
• Diff sandbox code