Module : Arguments

Ce module permet de traiter facilement les arguments passés depuis #invoke. C'est un méta-module, destiné à être utilisé par d'autres modules, et ne doit pas être appelé directement depuis #invoke. Ses caractéristiques comprennent :

• Coupe facile des arguments et suppression des arguments vides.
• Les arguments peuvent être transmis à la fois par le cadre actuel et par le cadre parent en même temps. (Plus de détails ci-dessous.)
• Les arguments peuvent être transmis directement depuis un autre module Lua ou depuis la console de débogage.
• Les arguments sont récupérés selon les besoins, ce qui peut aider à éviter (certains) problèmes avec les balises ref.
• La plupart des fonctionnalités peuvent être personnalisées.

Contenu

• 1 Utilisation de base
  • Options de 1.1
  • 1.2 Découpage et suppression des blancs
  • 1.3 Formatage personnalisé des arguments
  • 1.4 Cadres et cadres parents
  • 1.5 Emballages
  • 1.6 Écriture dans la table args
  • 1.7 Balises de référence
  • 1.8 Limites connues

Utilisation de base

Tout d'abord, vous devez charger le module. Il contient une fonction, nommée getArgs.

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

Dans le scénario le plus basique, vous pouvez utiliser getArgs dans votre fonction principale. La variable args est une table contenant les arguments de #invoke. (Voir ci-dessous pour plus de détails.)

local getArgs = require('Module:Arguments').getArgs local p = {} function p.main(frame) local args = getArgs(frame) -- Le code du module principal va ici. fin retour p

Cependant, la pratique recommandée consiste à utiliser une fonction uniquement 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 = {} fonction p.main(frame) local args = getArgs(frame) return p._main(args) end function p._main(args) -- Main le code du module va ici. retour fin p

Si vous souhaitez que plusieurs fonctions utilisent les arguments, et que vous souhaitez également qu'elles soient accessibles à partir de #invoke, vous pouvez utiliser une fonction wrapper.

local getArgs = require('Module:Arguments').getArgs fonction locale makeInvokeFunc(funcName) return fonction (frame) local args = getArgs(frame) return p[funcName](args) end end local p = {} p.func1 = makeInvokeFunc('_func1') function p._func1(args) -- Le code de la première fonction va ici. end p.func2 = makeInvokeFunc('_func2') function p._func2(args) -- Le code de la deuxième fonction va ici. fin retour p

Les options

Les options suivantes sont disponibles. Ils sont expliqués 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 :Un modèle de wrapper', 'Template:Another wrapper template' }, readOnly = true, noOverwrite = true })

Découpage et suppression des blancs

Les arguments vides font souvent trébucher les codeurs novices dans la conversion de modèles de page Mediaweb en Lua. Dans la syntaxe des modèles, les chaînes vides et les chaînes constituées uniquement d'espaces sont considérées comme fausses. Cependant, dans Lua, les chaînes vides et les chaînes constituées d'espaces blancs sont considérées comme vraies. Cela signifie que si vous ne faites pas attention à de tels arguments lorsque vous écrivez vos modules Lua, vous pourriez traiter quelque chose comme vrai qui devrait en fait être traité comme faux. Pour éviter cela, par défaut, ce module supprime tous les arguments vides.

De même, les espaces peuvent causer des problèmes lors du traitement des arguments positionnels. Bien que les espaces blancs soient coupés pour les arguments nommés provenant de #invoke, ils sont conservés pour les arguments positionnels. La plupart du temps, cet espace supplémentaire n'est pas souhaité, donc ce module le supprime par défaut.

Cependant, vous souhaitez parfois utiliser des arguments vides en entrée, et parfois vous souhaitez conserver des espaces blancs supplémentaires. Cela peut être nécessaire pour convertir certains modèles exactement comme ils ont été écrits. Si vous voulez faire cela, vous pouvez définir les arguments trim et removeBlanks sur false.

arguments locaux = getArgs(frame, { trim = false, removeBlanks = false })

Formatage personnalisé des arguments

Parfois, vous souhaitez supprimer certains arguments vides mais pas d'autres, ou peut-être souhaiterez-vous mettre tous les arguments de position en minuscules. Pour faire des choses comme ça, vous pouvez utiliser l'option valueFunc. L'entrée de cette option doit être une fonction qui prend deux paramètres, key et value, et renvoie une seule valeur. Cette valeur est ce que vous obtiendrez lorsque vous accéderez à la clé de champ dans la table args.

Exemple 1 : cette fonction préserve les espaces pour le premier argument positionnel, mais supprime tous les autres arguments et supprime tous les autres arguments vides.

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

Exemple 2 : cette fonction supprime les arguments vides et convertit tous les arguments en minuscules, mais ne supprime pas les espaces blancs 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 fin retour nil fin })

Remarque : les fonctions ci-dessus échoueront si vous passez une entrée qui n'est pas de type string ou nil. Cela peut ê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 devrez vérifier le type de votre entrée. Ce n'est pas un problème si vous utilisez une fonction spécialement pour les arguments de #invoke (c'est-à-dire que vous avez des fonctions p.main et p._main, ou quelque chose de similaire).

Exemples 1 et 2 avec vérification de type 1 Exemple:

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

2 Exemple:

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

Notez également 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, vous devez vous assurer que vous ne faites rien d'inefficace avec votre code.

Cadres et cadres parents

Les arguments de la table args peuvent être transmis à partir du cadre actuel ou de son cadre parent en même temps. Pour comprendre ce que cela signifie, il est plus facile de donner un exemple. Disons que nous avons un module appelé Module:ExampleArgs. Ce module imprime les deux premiers arguments positionnels qui lui sont passés.

Module : exemple de code Args

local getArgs = require('Module:Arguments').getArgs local p = {} fonction p.main(frame) local args = getArgs(frame) return p._main(args) end function p._main(args) local first = args[1] ou '' local second = args[2] ou '' return first .. ' ' .. second end return p

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

Maintenant, si nous appelions Template:ExampleArgs, ce qui suit se produirait :

Vous pouvez définir trois options pour modifier ce comportement : frameOnly, parentOnly et parentFirst. Si vous définissez frameOnly, seuls les arguments passés à partir du cadre actuel seront acceptés ; si vous définissez parentOnly, seuls les arguments passés depuis le cadre parent seront acceptés ; et si vous définissez parentFirst, les arguments seront transmis à la fois à partir des cadres actuel et parent, mais le cadre parent aura la priorité sur le cadre actuel. Voici les résultats en termes de Template :ExampleArgs :

cadreSeul parentSeul parentPremier

:

1. Si vous définissez à la fois les options frameOnly et parentOnly, le module ne récupérera aucun argument de #invoke. Ce n'est probablement pas ce que vous voulez.
2. Dans certaines situations, une trame parent peut ne pas être disponible, par exemple si getArgs est passé à la trame parent plutôt qu'à la trame actuelle. Dans ce cas, seuls les arguments du cadre seront utilisés (sauf si parentOnly est défini, auquel cas aucun argument ne sera utilisé) et les options parentFirst et frameOnly n'auront aucun effet.

Emballages

L'option wrappers est utilisée pour spécifier un nombre limité de templates comme templates wrapper, c'est-à-dire des templates dont le seul but est d'appeler un module. Si le module détecte qu'il est appelé à partir d'un modèle wrapper, il vérifiera uniquement les arguments dans le cadre parent ; sinon, il ne vérifiera que les arguments dans le cadre passé à getArgs. Cela permet aux modules d'être appelés par #invoke ou via un modèle de wrapper sans la perte de performances associée à la nécessité de vérifier à la fois le cadre et le cadre parent pour chaque recherche d'argument.

Les wrappers peuvent être spécifiés soit sous forme de chaîne, soit sous forme de tableau de chaînes.

arguments locaux = getArgs(frame, { wrappers = 'Template:Wrapper template' })

local args = getArgs(frame, { wrappers = { 'Template:Wrapper 1', 'Template:Wrapper 2', -- N'importe quel nombre de modèles de wrapper peut être ajouté ici. } })

:

1. Le module détectera automatiquement s'il est appelé à partir de la sous-page /sandbox d'un modèle de wrapper, il n'est donc pas nécessaire de spécifier explicitement les pages sandbox.
2. L'option wrappers modifie effectivement la valeur par défaut des options frameOnly et parentOnly. Si, par exemple, parentOnly était explicitement défini sur false avec les wrappers définis, les appels via les modèles de wrapper entraîneraient le chargement des arguments frame et parent, bien que les appels non via les modèles de wrapper entraîneraient le chargement uniquement des arguments frame.
3. Si l'option wrappers est définie et qu'aucun cadre parent n'est disponible, le module obtiendra toujours les arguments du cadre passé à getArgs.

Écriture dans la table args

Parfois, il peut être utile d'écrire de nouvelles valeurs dans la table args. Ceci est possible avec les paramètres par défaut de ce module. (Cependant, gardez à l'esprit qu'il est généralement préférable de créer une nouvelle table avec vos nouvelles valeurs et de copier les arguments de la table args si nécessaire.)

args.foo = 'une certaine valeur'

Il est possible de modifier ce comportement avec les options readOnly et noOverwrite. Si readOnly est défini, il n'est pas du tout possible d'écrire des valeurs dans la table args. Si noOverwrite est défini, il est alors possible d'ajouter de nouvelles valeurs à la table, mais il n'est pas possible d'ajouter une valeur si cela écraserait les arguments passés depuis #invoke.

Balises de référence

Ce module utilise des métatables pour récupérer les arguments de #invoke. Cela permet d'accéder à la fois aux arguments du cadre et aux arguments du cadre parent sans utiliser la fonction paires(). Cela peut aider si votre module peut recevoir des balises ref en entrée.

Dès que les balises ref sont accessibles depuis Lua, elles sont traitées par le logiciel de page Mediaweb et la référence apparaîtra dans la liste de références en bas de l'article. Si votre module continue d'omettre la balise de référence de la sortie, vous vous retrouverez avec une référence fantôme - une référence qui apparaît dans la liste de références, mais aucun numéro qui y est lié. Cela a posé un problème avec les modules qui utilisent paires() pour détecter s'il faut utiliser les arguments du cadre ou du cadre parent, car ces modules traitent automatiquement chaque argument disponible.

Ce module résout ce problème en autorisant l'accès aux arguments du cadre et du cadre parent, tout en ne récupérant ces arguments que lorsque cela est nécessaire. Cependant, le problème persistera si vous utilisez des paires (args) ailleurs dans votre module.

limitations connues

L'utilisation de métatables a aussi ses inconvénients. La plupart des outils de table Lua normaux ne fonctionneront pas correctement sur la table args, y compris l'opérateur #, la fonction next() et les fonctions de la bibliothèque de tables. Si leur utilisation est importante pour votre module, vous devez utiliser votre propre fonction de traitement d'arguments au lieu de ce module.

-- Ce module permet de traiter facilement les arguments passés à Scribunto depuis -- #invoke. Il est destiné à être utilisé par d'autres modules Lua et ne doit pas être appelé directement depuis #invoke. local libraryUtil = require('libraryUtil') local checkType = libraryUtil.checkType arguments locaux = {} -- Génère quatre fonctions tidyVal différentes, afin que nous n'ayons pas à vérifier les -- options chaque fois que nous l'appelons. fonction locale tidyValDefault(key, val) if type(val) == 'string' then val = val:match('^%s*(.-)%s*$') if val == '' then return nil else return val end else return val end end fonction locale tidyValTrimOnly(key, val) if type(val) == 'string' then return val:match('^%s*(.-)%s*$') else return val end end fonction locale tidyValRemoveBlanksOnly(key, val) if type(val) == 'string' then if val:find('%S') then return val else return nil end else return val end end end fonction locale tidyValNoChange(key, val ) return val end fonction locale matchesTitle(donné, titre) local tp = type(donné) return (tp == 'string' ou tp == 'number') et mw.title.new( given ).prefixedText == title end local translate_mt = { __index = function(t, k) return k end } function arguments.getArgs(frame, options) checkType('getArgs', 1, frame, 'table', true) checkType('getArgs', 2, options , 'table', true) frame = frame ou {} options = options ou {} --[[ -- Configure la traduction des arguments. --]] options.translate = options.translate ou {} if getmetatable(options.translate) == nil then setmetatable(options.translate, translate_mt) end if options.backtranslate == nil then options.backtranslate = {} pour k ,v par paires(options.translate) do options.backtranslate[v] = k end end if options.backtranslate et getmetatable(options.backtranslate) == nil then setmetatable(options.backtranslate, { __index = function(t, k) if options.translate[k] ~= k then return nil else return k end end }) end --[[ -- Récupère les tables d'arguments. Si un objet frame valide nous a été transmis, récupérez les -- arguments frame (fargs) et les arguments frame parent (pargs), en fonction -- des options définies et de la disponibilité du frame parent. Si nous n'étions pas -- passé un objet frame valide, nous sommes appelés à partir d'un autre module Lua -- ou à partir de la console de débogage, alors supposons que nous avons reçu une table d'arguments -- directement, et affectez-la à une nouvelle variable (luaArgs). --]] local fargs, pargs, luaArgs if type(frame.args) == 'table' and type(frame.getParent) == 'function' then if options.wrappers then --[[ -- L'option wrappers rend Module:Arguments recherche des arguments dans -- soit la table d'arguments du cadre, soit la table d'arguments parent, mais -- pas les deux. Cela signifie que les utilisateurs peuvent utiliser soit la syntaxe #invoke -- soit un modèle de wrapper sans perte de performances associée -- en recherchant des arguments à la fois dans le cadre et dans le cadre parent. -- Module:Arguments recherchera les arguments dans le cadre parent -- s'il trouve le titre du cadre parent dans options.wrapper ; -- sinon, il recherchera les arguments dans l'objet frame passé -- à getArgs. --]] local parent = frame:getParent() sinon parent then fargs = frame.args else local title = parent:getTitle():gsub('/sandbox$', '') local found = false si matchTitle(options .wrappers, title) then found = true elseif type(options.wrappers) == 'table' then for _,v in pairs(options.wrappers) do if matchesTitle(v, title) then found = true break end end end - - Nous testons spécifiquement false ici pour que nil (valeur par défaut) agisse comme true. si trouvé ou options.frameOnly == false then pargs = parent.args end if not found or options.parentOnly == false then fargs = frame.args end end else -- options.wrapper n'est pas défini, alors vérifiez les autres options . sinon options.parentOnly alors fargs = frame.args end sinon options.frameOnly then parent local = frame:getParent() pargs = parent et parent.args ou nil end end if options.parentFirst then fargs, pargs = pargs, fargs end else luaArgs = frame end -- Définit l'ordre de priorité des tables d'arguments. Si les variables sont -- nil, rien ne sera ajouté à la table, c'est ainsi que nous évitons les conflits -- entre les arguments frame/parent et les arguments Lua. local argTables = {fargs} argTables[#argTables + 1] = pargs argTables[#argTables + 1] = luaArgs --[[ -- Génère la fonction tidyVal. S'il a été spécifié par l'utilisateur, nous -- l'utilisons ; sinon, nous choisissons l'une des quatre fonctions en fonction des -- options choisies. C'est pour que nous n'ayons pas à appeler la table d'options -- chaque fois que la fonction est appelée. --]] local tidyVal = options.valueFunc if tidyVal then if type(tidyVal) ~= 'function' then error( "mauvaise valeur attribuée à l'option 'valueFunc'" .. '(fonction attendue, a ' .. type(tridyVal) .. ')', 2 ) end elseif options.trim ~= false then if options.removeBlanks ~= false then tidyVal = tidyValDefault else tidyVal = tidyValTrimOnly end else if options.removeBlanks ~= false then tidyVal = tidyValRemoveBlanksOnly else tidyVal = tidyValNoChange end end -[[ -- Configure les tables args, metaArgs et nilArgs. args sera celui - accessible à partir des fonctions, et metaArgs contiendra les arguments réels. Nil -- les arguments sont mémorisés dans nilArgs, et la métatable les connecte tous -- ensemble. --]] local args, metaArgs, nilArgs, metatable = {}, {}, {}, {} setmetatable(args, metatable) fonction locale mergeArgs(tables) --[[ -- Accepte plusieurs tables en entrée et fusionne leurs clés et valeurs -- dans une seule table. Si une valeur est déjà présente, elle n'est pas écrasée ; -- les tables listées plus haut sont prioritaires. Nous mémorisons également des valeurs nulles, qui peuvent être écrasées si elles sont « s » (soft). --]] pour _, t dans ipairs(tables) do for key, val in pair(t) do if metaArgs[key] == nil et nilArgs[key] ~= 'h' then local tidiedVal = tidyVal(key, val) if tidiedVal == nil then nilArgs[key] = 's' else metaArgs[key] = tidiedVal end end end end end --[[ -- Définit le comportement métatable. Les arguments sont mémorisés dans la table metaArgs et ne sont extraits des tables d'arguments qu'une seule fois. La récupération des arguments -- à partir des tables d'arguments est l'étape la plus gourmande en ressources de ce -- module, nous essayons donc de l'éviter dans la mesure du possible. Pour cette raison, nil -- les arguments sont également mémorisés, dans la table nilArgs. De plus, nous gardons un enregistrement -- dans la métatable du moment où les paires et les paires ont été appelées, donc nous n'exécutons pas les paires et les paires plus d'une fois sur les tables d'arguments. Nous n'exécutons pas non plus ipairs sur fargs et pargs si les paires ont déjà été exécutées, car tous les arguments auront déjà été copiés. --]] metatable.__index = function (t, key) --[[ -- Récupère un argument lorsque la table args est indexée. D'abord, nous vérifions -- pour voir si la valeur est mémorisée, et sinon nous essayons de la récupérer depuis -- les tables d'arguments. Lorsque nous vérifions la mémorisation, nous devons vérifier -- metaArgs avant nilArgs, car les deux peuvent être non nuls en même temps. -- Si l'argument n'est pas présent dans metaArgs, nous vérifions également si --pairs a déjà été exécuté. Si les paires ont déjà été exécutées, nous renvoyons nil. -- C'est parce que tous les arguments auront déjà été copiés dans -- metaArgs par la fonction mergeArgs, ce qui signifie que tout autre argument -- doit être nul. --]] if type(key) == 'string' then key = options.translate[key] end local val = metaArgs[key] if val ~= nil then return val elseif metatable.donePairs ou nilArgs[key] then return nil end for _, argTable in ipairs(argTables) do local argTableVal = tidyVal(key, argTable[key]) if argTableVal ~= nil then metaArgs[key] = argTableVal return argTableVal end end nilArgs[key] = 'h' return nil end metatable.__newindex = function (t, key, val) -- Cette fonction est appelée lorsqu'un module essaie d'ajouter une nouvelle valeur à la table -- args, ou essaie de modifier une valeur existante. if type(key) == 'string' then key = options.translate[key] end if options.readOnly then error( 'impossible d'écrire dans la table d'argument key "' .. tostring(clé) .. '"; la table est en lecture seule', 2 ) elseif options.noOverwrite and args[key] ~= nil then error( 'impossible d'écrire dans la table d'argument key "' .. tostring(clé) .. '"; écraser les arguments existants n'est pas autorisé', 2 ) elseif val == nil then --[[ -- Si l'argument doit être écrasé par nil, nous devons effacer -- la valeur dans metaArgs, de sorte que __index, __pairs et __ipairs n'utilisent pas une valeur existante précédente, si elle est présente ; et nous avons également besoin de mémoriser le nil dans nilArgs, afin que la valeur ne soit pas recherchée dans les tables d'arguments si on y accède à nouveau. --]] metaArgs[key] = nil nilArgs[key] = 'h' else metaArgs[key] = val end end fonction locale translatenext(invariant) local k, v = next(invariant.t, invariant.k) invariant. k = k if k == nil then return nil elseif type(k) ~= 'string' or not options.backtranslate then return k, v else local backtranslate = options.backtranslate[k] if backtranslate == nil then -- Ignorer celui-ci. Ceci est un appel de queue, donc cela ne provoquera pas de débordement de pile return translatenext(invariant) else return backtranslate, v end end end metatable.__pairs = function () -- Appelé lorsque les paires sont exécutées sur la table args. sinon metatable.donePairs then mergeArgs(argTables) metatable.donePairs = true end return translatenext, { t = metaArgs } end local function inext(t, i) -- Ceci utilise notre métaméthode __index local v = t[i + 1] if v ~= nil then return i + 1, v end end metatable.__ipairs = function (t) -- Appelé lorsque ipairs est exécuté sur la table args.