Module:Arguments/doc

Attention:

Ne pas modifier. Cette page est maintenue par un bot. Toutes les modifications doivent être effectuées sur mediawiki.org. (traduisez cet avertissement) Merci de nous aider à traduire cette page.

Ce module facilite le traitement des arguments reçus de Template:Magic word. 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 Template:Xtag.
• 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
})

Template:Collapse top 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.

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 :

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

Il existe trois options qui vous permettent de modifier ce comportement : frameOnly, parentOnly et parentFirst. Si vous définissez frameOnly alors seulement les arguments passés du frame courant seront acceptés; si vous définissez parentOnly alors seulement les arguments passés du frame parent seront acceptés. Et si vous définirez parentFirst 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 Template:ExampleArgs :

frameOnly

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

parentOnly

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

parentFirst

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

Conteneurs

L'option wrappers 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 à getArgs. Cela permet d'appeler les modules soit par {{#invoke:...}} 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 {{Navbox}} est {{#invoke:Navbox|navbox}} (en excluant le contenu entre les balises <noinclude>...</noinclude>). Il n'est pas utile de vérifier les arguments transmis directement à la déclaration {{#invoke:...}} pour ce modèle, car aucun argument n'y sera jamais spécifié. Nous pouvons éviter de vérifier les arguments passés à {{#invoke:...}} en utilisant l'option parentOnly , mais si nous le faisons, {{#invoke:...}} ne fonctionnera pas non plus depuis les autres pages. Si c'était le cas, alors Template:Tmpl dans le code Template:Tmpl serait complètement ignoré, quelque soit la page où il a été utilisé. En utilisant l'option wrappers pour indiquer que Template:Navbox est un conteneur, nous pouvons faire que Template:Tmpl 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.

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

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. (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 args selon les besoins).

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. Si noOverwrite 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 {{#invoke:...}}.

Balises ref

Cemodule utilise les métatables pour récupérer les arguments de {{#invoke:...}}. Cela permet d'accéder aux arguments du frame et à ceux du parent sans passer par la fonction pairs(). Cela peut vous aider si votre module a reçu des balises Template:Xtag en entrée.

Dès que les balises Template:Xtag 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 pairs() 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 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. 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.