Module:Outils/Documentation

Ceci est la page de documentation pour Module:Outils

Ce module contient différentes fonction pratiques.

Résumé des fonctions

Fonctions exportables :

trim( texte ) – similaire à mw.text.trim mais retourne nil lorsque la chaine est vide ou lorsque le paramètre n'est pas une chaine (ne génère pas d'erreur).
erreur( texte ) – destiné à afficher un message d'erreur en gros et rouge. Retourne la chaine transmise dans un span de class "error". Par défaut erreur : raison non précisée.
extractArgs( frame, ... ) – retourne une table avec les paramètres, à partir d'un objet frame, d'une table ou d'une liste de paramètre.
validTextArg( args, name, ... ) – retourne le premier paramètre chaine non vide à partir de la table des paramètres et d'une liste de nom de paramètre.
notEmpty( var, ... ) – retourne le premier élément non vide.
abr( frame, ... ) – génère une abréviation discrète (ou non)
nobr( texte ) – équivalent de {{nobr}}, transforme le texte fournie en texte insécable.
ordinal( nombre, feminin ) – retourne un ordinal abrégé comme {{1er}}, {{2e}}… à partir d'un nombre ou d'une chaine contenant uniquement des chiffres. Si le deuxième est défini, retourne 1^re au lieu de 1^er.
nombre2texte_reel(pnombre, plangue, ptype, porthographe, pgenre, pmajuscule) – transforme un nombre en texte (5 → cinq ou cinquième). Gère la langue (fr, be, ch), l'orthographe pré ou post 1990, le genre ainsi que les variantes locales des nombres.
nombre2texte(frame) – similaire à nombre2texte_reel mais pour un appel depuis un modèle.
premiereValeur(frame) – retourne son premier paramètre non vide (au sens de trim())

Modules externes et autres éléments dont ce module a besoin pour fonctionner :

Module:Outils/Data – pour les conversions nombre → texte.

Détail par fonction

extractArgs

Syntaxe

Outils.extractArgs( frame, ... )

si frame n'est pas une table, retourne { frame, ... }
Si frame est une table simple et non une objet Frame, retourne frame
Si frame est un objet créé par #invoke:, retourne les paramètres passé à #invoke: (en priorité) et ceux passées au modèle. Si le paramètre invokeArgsOnly n'est pas vide, seul les paramètres transmis à invoke seront utilisés.

Attention : cette fonction peut modifier la table frame.getParent().args. S'il est probable qu'un autre module passe un objet frame à votre fonction, il est préférable de l'indiquer dans la documentation.

Exemple

function p.maFonction( frame, ... )
    local args = Outils.extractArgs( frame, ... )
    return ( args[1] or 'nil' ) .. ' ' .. ( args[2] or 'nil' ) .. ' ' .. ( args['nom'] or 'nil' )
end

appel direct : p.maFonction( 'oui', 'deux', 'Zebulon84' ) → « oui deux nil » (impossible de transmettre un paramètre nommé)
appel par table : p.maFonction{ 'oui', 'deux', nom = 'Zebulon84' } → « oui deux Zebulon84 »
appel par #invoke: : {{#invoke:p |maFonction |oui |2 |nom = Zebulon84}} → « oui deux Zebulon84 »
appel par modèle {{Ma fonction}} :
- le modèle contient {{#invoke:p |maFonction}},
  - {{Ma fonction|oui | deux |nom= Zebulon84}} → « oui deux Zebulon84 »
- le modèle contient {{#invoke:p |maFonction |nom = Zebulon84}}
  - {{Ma fonction |oui | deux }} → « oui deux Zebulon84 »
  - {{Ma fonction |oui | deux |nom = Hexasoft}} → « oui deux Zebulon84 »
- le modèle contient {{#invoke:p |maFonction |nom = {{{nom|Zebulon84}}} }}
  - {{Ma fonction |oui | deux }} → « oui deux Zebulon84 »
  - {{Ma fonction |oui | deux |nom = Hexasoft}} → « oui deux Hexasoft »
  - {{Ma fonction |oui | deux |nom = }} → « oui deux nil »
- le modèle contient {{#invoke:p |maFonction |nom = {{{nom|Zebulon84}}} |invokeArgsOnly = oui}}
  - {{Ma fonction |oui | deux }} → « nil nil Zebulon84 »
  - {{Ma fonction |oui | deux |nom = Hexasoft}} → « nil nil Hexasoft»

validTextArg

Syntaxe

Outils.validTextArg( args, name, ... )

Retourne args.name si c'est un texte valide. Sinon teste les autres éléments transmis à la fonction. S'il n'y en a pas ou s'ils ne correspondent pas à un texte valide dans la table args, retourne nil

Cette fonction est pratique pour obtenir le contenu d'un paramètre pouvant avoir plusieurs noms.

Attention : les nombres (type 'number') ne sont pas considérés comme un texte valide.

exemple

local args = { '1', '2', 3, nom1 = nil, nom2 = '', nom3 = 'a' }
local v1  = Outils.validTextArg( args, 'nom1' }                -- v1 = nil
local v2 = Outils.validTextArg( args, 'nom1', 'nom2', 'nom3' ) -- v2 = 'a'
local v3 = Outils.validTextArg( args, 3, 2, 1 )                -- v3 = '2'

local function validArg( ... ) 
    return Outils.validTextArg( args, ... }
end

local v4 = validArg( 'nom' )  -- v4 = nil
local v5 = validArg( 'nom2', 'nom3' ) -- v5 = 'a'

notEmpty

Outils.notEmpty( var, ... )

Retourne le premier élément non vide, sinon retourne nil.

Sont considérés comme vide : nil, false, '', ' \t \n ', 0, { }
Sont considérés comme non vide : true, 'blabla', ' ', 1, { '' }, { {} }, function () end

abr

Syntaxe

Outils.abr( frame, ... )
Outils.abr( abréviation, signification, langue )
Outils.abr{ abréviation, signification, langue, nbsp = '+', visible = true }

Génère une abréviation (discrète par défaut)

Paramètres

abréviation – texte qui sera visible,
signification – signification de l’abréviation à afficher dans l’infobulle,
Langue – Code de langue pour l’abréviation,
nbsp – permet d'insérer une espace insécable avant (si nbsp = '-') ou après (si nbsp = '+') l'abréviation.
visible – souligne l’abréviation en pointillé

exemple

{{#invoke:Outils |abr |hab. |Nombre d’habitants |visible = oui}} → Erreur de script : la fonction « abr » n’existe pas.

local hab = 36 .. Outils.abr{ 'hab.', 'Nombre d’habitants', nbsp = '-', visible = true }
 -- hab = '36&nbsp;<abbr title="Nombre d’habitants">hab.</abbr>'

nombre2texte_reel

Syntaxe

Outils.nombre2texte_reel( pnombre, plangue, ptype, porthographe, pgenre, pmajuscule )

Retourne la forme textuelle du nombre passé en paramètre. Supporte l'orthographe pré/post 1990, la création d'ordinaux ou de cardinaux, et les variantes de certains nombres (septante, nonante, huitante…).

Contraintes

ne traite que les nombres entre -999999999999 et 999999999999 (inclus)
ne gère pas les nombres à virgule (la partie décimale est ignorée, la partie entière est traitée)
pour les ordinaux seuls les nombres positifs sont traités (un nombre négatif est accepté mais son signe est ignoré)

Paramètres

pnombre – doit être un string. Le nombre à convertir
plangue – langue utilisée. Valeur possibles : "fr" (soixante-dix, quatre-vingts, quatre-vingt-dix) ; "be" (septante, quatre-vingts, nonante) ; "ch" (septante, huitante, nonante) ; "ch2" (septante, octante, nonante). Une valeur nil correspond à "fr"
ptype – le type de sortie. Seules valeurs possibles : nil ou "ordinal". Si "ordinal" l'ordinal correspondant au nombre est généré (exemple : 12 → "douzième") sinon un cardinal est généré (exemple : 12 → "douze"). nil correspond à un cardinal
porthographe – le type d'orthographe suivi. Valeurs possibles : nil ou "réformée". Si "réformée" l'orthographe post-1990 est utilisé (tirets entre chaque termes) sinon c'est l'orthographe « historique » qui est suivie
pgenre – le genre du nombre. Valeurs possibles : nil ou "féminin". Si "féminin" la seule différence est pour les ordinaux ("premier" devient "première"), aucun changement pour les autres cas
pmajuscule – mettre une majuscule à la première lettre. Valeurs possibles : nil ou "oui". Si "oui" la première lettre du résultat est passée en majuscule, elle reste en minuscule sinon

Exemples

Voir ci-dessous.

nombre2texte

Même fonction que ci-dessus mais pour appel depuis un article (via un modèle).

Paramètres

premier paramètre non nommé – le nombre à convertir (format numérique)
langue= – la langue utilisée (absent ou "fr", "be", "ch" ou "ch2", voir ci-dessus)
orthographe= – l'orthographe suivie (absent, "réformée", voir ci-dessus)
genre= – le genre du résultat (absent, "féminin", voir ci-dessus)
majuscule= – mettre une majuscule à la première lettre (absent, "oui", voir ci-dessus)
type – générer un cardinal ou un ordinal (absent, "ordinal", voir ci-dessus)

Exemples

Appel de base : {{#invoke:Outils|nombre2texte|132}} → Erreur de script : la fonction « nombre2texte » n’existe pas.
Ordinal : {{#invoke:Outils|nombre2texte|132|type=ordinal}} → Erreur de script : la fonction « nombre2texte » n’existe pas.
Majuscule : {{#invoke:Outils|nombre2texte|132|majuscule=oui}} → Erreur de script : la fonction « nombre2texte » n’existe pas.
Langue : {{#invoke:Outils|nombre2texte|198|langue=be}} → Erreur de script : la fonction « nombre2texte » n’existe pas.
Genre : {{#invoke:Outils|nombre2texte|1|genre=féminin|type=ordinal}} → Erreur de script : la fonction « nombre2texte » n’existe pas.
Orthographe : {{#invoke:Outils|nombre2texte|1927|orthographe=réformée}} → Erreur de script : la fonction « nombre2texte » n’existe pas.

premiereValeur

Syntaxe

Outils.premiereValeur( frame )

Retourne le contenu du premier des paramètres passés à l'appel qui ne soit pas composé uniquement de séparateurs (espace, retour à la ligne, tabulation).

Contraintes

ne peut être appelé que directement (utilise frame.args), et non à travers un modèle

Paramètres

liste de paramètres non nommés

Exemples

{{#invoke:Outils|premiereValeur| p1 | p2 | p3}} retourne « Erreur de script : la fonction « premiereValeur » n’existe pas. »
{{#invoke:Outils|premiereValeur|| p2 | p3}} retourne « Erreur de script : la fonction « premiereValeur » n’existe pas. »
{{#invoke:Outils|premiereValeur| | | p3}} retourne « Erreur de script : la fonction « premiereValeur » n’existe pas. »