Help:Extension:ParserFunctions/fr

Cette extension MediaWiki est une collection de fonctions du parseur permettant la programmation au sein des modèles. Les fonctions du parseur ont cette syntaxe typique :



Fonctions
Ce module définit les fonctions suivantes pour le moment : #expr:, #ifexpr:, #if:, #ifeq:, #ifexist:, #rel2abs:, #time:, #timel:, #switch:</tt>, #rel2abs:</tt>...

#expr:
La fonction #expr:</tt> calcule des expressions mathématiques. La syntaxe est :

Les opérateurs booléens considèrent toute valeur numérique valide non nulle comme vraie et 0 comme faux. Les nombres doivent être écris avec leur décimale marquée par le point décimal «. ».

Le résultat de #expr sera formaté sous forme décimale, en utilisant la notation exponentielle si l’exposant de base 10 sort de l’intervalle -4 à 9, mais durant le calcul la précision interne de calcul est plus élevée et utilise des nombres réels codés en binaire en double précision, conformément à la norme IEEE 754 (53 bits de mantisse, un bit de signe et 12 bits pour l'exposant de base 2). Certaines fonctions décrites ci-dessous ont toutefois une précision plus limitée (notamment les fonctions logarithmiques, exponentielles, et trigonométriques). La précision effective de certains calculs dépend de la précision des bibliothèques mathématiques compilées dans la version de PHP installée sur le serveur, et même avec des bibliothèques conformes à la norme IEEE 754, les marges de tolérance peuvent varier d’un système à l’autre.

Certains calculs peuvent donner un résultat infini (INF) ou non significatif (NAN) qui n'est pas considéré comme une erreur dans les calculs mais sera retourné dans la chaîne du résultat final. Cette chaîne ne peut alors pas être reconnue dans une autre expression #expr:</tt> englobante et produira une erreur, alors que la fonction #iferror:</tt> (voir-ci-dessous) ne détecte pas la validité de ces résultats. On peut y pallier en englobant l’évaluation de #expr:</tt> dans une autre expression #expr:</tt> qui sera testée par #iferror:</tt>. Par exemple :


 *  </tt> retourne «  » qui est détecté par #iferror:</tt> :
 *  </tt> retourne «  ».
 *  </tt> retourne «  » qui n’est pas détecté directement par #iferror:</tt>
 *  </tt> retourne «  ».
 *  </tt> retourne «  ».

Une des opérations (mod</tt>) utilise uniquement la précision des entiers supportés par le système PHP sur laquelle MediaWiki est installé. Pour les applications mathématiques, on lui préférera l’emploi de l’opérateur <tt>floor</tt> afin de correctement effectuer les divisions entières sur un domaine de valeurs plus étendu et calculer le reste réel de cette division.

Les opérateurs supportés (classés par ordre de priorité de traitement) sont :

!| Priorité !| Type !| Opérateurs !| Exemples
 * -valign="top"

!| 1 <tt> </tt> =
 * -valign="top"
 * Groupement d’évaluation prioritaire (parenthèses)
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"|

<tt> </tt> =

<tt> </tt> =

!| 2 <tt> </tt> =
 * -valign="top"
 * Nombres décimaux et constantes
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| 1234.5 e pi

<tt> </tt> =

<tt> </tt> =

! rowspan="7"| 3 <tt> </tt> =
 * -valign="top"
 * Changements de signe (fonction ou opérateur monadique)
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| + - abs

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

(inférieur, vers zéro, ou supérieur) <tt> </tt> =
 * -valign="top"
 * Arrondis à un entier proche (fonction ou opérateur monadique)
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| floor trunc ceil

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

(de base e) <tt> </tt> =
 * -valign="top"
 * Logarithme naturel ou népérien
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| ln

<tt> </tt> =  (= log10 1000)

<tt> </tt> =  (= log2 8)

(angles exprimé en radians) <tt> </tt> =
 * -valign="top"
 * Sinus et arcsinus
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| sin asin

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

(angles exprimé en radians) <tt> </tt> =
 * -valign="top"
 * Cosinus et arccosinus
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| cos acos

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

(angles exprimé en radians) <tt> </tt> =  (résultat qui devrait être nul, mais souvent proche de zéro et de signe indéterminé)
 * -valign="top"
 * Tangeante et arctangeante
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| tan atan

<tt> </tt> =  (résultat de signe indéterminé et de valeur absolue très grande mais indéfinie, ou bien erreur)

<tt> </tt> =

<tt> </tt> =  (résultat de signe indéterminé et de valeur absolue très grande mais indéfinie, ou bien erreur)

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =  (résultat qui devrait être nul, mais souvent proche de zéro et de signe indéterminé)

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =
 * -valign="top"
 * Non logique (retourne 1 si le paramètre est égal à zéro, sinon retourne 0)
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| not

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

(limité entre -323 et +308 : en deça donne zéro, au delà donne l’infini) <tt> </tt> =  (infini, car exposant supérieur à la limite haute)
 * -valign="top"
 * rowspan="2"| 4
 * Multiplication par une puissance de 10
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| e

<tt> </tt> =

<tt> </tt> =  (notation exponentielle utilisée dans ce résultat)

<tt> </tt> =  (pas de notation exponentielle dans ce résultat)

<tt> </tt> =  (pas de notation exponentielle dans ce résultat)

<tt> </tt> =  (pas de notation exponentielle dans ce résultat)

<tt> </tt> =  (notation exponentielle utilisée dans ce résultat)

<tt> </tt> =  (notation exponentielle utilisée dans le résultat)

<tt> </tt> =

<tt> </tt> =  (et non comme le précédent)

<tt> </tt> =  (plus petit nombre représentable, arrondi ici)

<tt> </tt> =  (résultat arrondi au dessus)

<tt> </tt> =  (résultat arrondi à zéro)

<tt> </tt> =  (zéro, car exposant inférieur à la limite basse)

<tt> </tt> =
 * -valign="top"
 * Exponentiation
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| ^

<tt> </tt> =  (racine carrée de 2)

<tt> </tt> =  (élément absorbant)

<tt> </tt> =

<tt> </tt> =  (élément absorbant)

<tt> </tt> =  (inversion du logarithme)

Attention : l’opérateur  n’est pas un reste au sens mathématique du terme, il tronque d'abord ses opérandes à l’entier le plus proche dont la valeur absolue est inférieure celle du nombre, puis réduit ces entiers sur 32 bits. Il effectue ensuite la division entière des deux opérandes entiers obtenus, et retourne le reste de cette division, du même signe que le quotient entier, et toujours inférieur, en valeur absolue, à celle du diviseur entier. Il retourne une erreur si la valeur absolue du diviseur n'est pas supérieure ou égal à 1 ; il retourne toujours 0 si le diviseur n'est pas au moins égal à 2 en valeur absolue. <tt> </tt> =
 * -valign="top"
 * 5
 * Produit, division ou reste (de gauche à droite)
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| * / div mod

<tt> </tt> =

<tt> </tt> =  (opérateur synonyme, identique à la division réelle)

<tt> </tt> =  (modulo entier, voir note ci-contre)

<tt> </tt> =

<tt> </tt> =  (identique à la division réelle)

<tt> </tt> =  (reste de la division des opérandes d’abord tronqués en entiers)

<tt> </tt> =  (partie entière inférieure de la division)

<tt> </tt> =  (reste de cette dernière division)

<tt> </tt> =
 * -valign="top"
 * 6
 * Somme ou différence (de gauche à droite)
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| + -

<tt> </tt> =

<tt> </tt> =
 * -valign="top"
 * 7
 * Arrondit à n décimales, pour limiter la précision de l’affichage.
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| round

Attention aux approximations numériques des résultats intermédiaires. Une très faible différence peut suffire (notamment pour les fonctions trigonométriques, logarithmes et exponentielles). <tt> </tt> =
 * -valign="top"
 * rowspan="3"| 8
 * Relation d’égalité numérique
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| = != &lt;&gt;

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =  (résultat non garanti, devrait être 1)

<tt> </tt> =  (résultat non garanti, devrait être 0)

<tt> </tt> =  (résultat non garanti, devrait être 1)

<tt> </tt> =  (résultat non garanti, devrait être 0)

<tt> </tt> =  (résultat non garanti, devrait être 1)

<tt> </tt> =  (résultat non garanti, devrait être 0)

<tt> </tt> =  (résultat non garanti, devrait être 0)

(inférieur ou égal à, supérieur ou égal à) <tt> </tt> =
 * -valign="top"
 * Relation d’ordre total
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| &lt;= &gt;=

<tt> </tt> =

(inférieur strictement à, supérieur strictement à) <tt> </tt> =
 * -valign="top"
 * Relation d’ordre partiel
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| &lt; &gt;

<tt> </tt> =

Tout opérande non nul est considéré comme vrai. Retourne 1 si les deux opérandes sont vrais, sinon retourne 0. <tt> </tt> =
 * -valign="top"
 * 9
 * Et logique
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| and

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =

Tout opérande non nul est considéré comme vrai. Retourne 0 si les deux opérandes sont faux, sinon retourne 1. <tt> </tt> =
 * -valign="top"
 * 10
 * Ou logique
 * style="word-spacing:0.5em;font-family:monospace;font-weight:bold"| or

<tt> </tt> =

<tt> </tt> =

<tt> </tt> =


 * }

Exemple :

donne :

qui correspond à 100 °F converti en °C, résultat arrondi au nombre entier le plus proche.

#ifexpr:
<tt>#ifexpr:</tt> évalue une expression mathématique (de la même façon que <tt>#ifexpr:</tt>) et renvoie une des chaînes en paramètres selon le résultat.

Si l’expression est évaluée à une valeur non nulle, alors renvoie le paramètre alors texte, sinon renvoie le paramètre sinon texte :

Si l’expression est évaluée à une valeur non nulle, alors renvoie le paramètre alors texte, sinon renvoie un texte vide :

Si l’expression ne peut pas être évaluée et retourne une erreur, la fonction <tt>#ifexpr:</tt> retourne cette erreur et non l’un des deux textes en paramètres :
 * <tt> </tt> retourne «  ».

Attention : bien que l’on ait :
 * <tt> </tt> qui retourne «  »,

l’expression en paramètre ne retourne pas un nombre fini (car il n’est pas exprimable dans les calculs intermédiaires en tant que nombre en virgule flottante double-précision IEEE 754) :
 * <tt> </tt> retourne «  »,

et ce nombre « infini » produit par la suite une erreur, s’il est réévalué par <tt>#ifexpr:</tt> (ou un autre <tt>#expr:</tt> englobant) :
 * <tt> </tt> retourne «  ».

#if:
La fonction <tt>#if:</tt> est une construction if-then-else. Sa syntaxe est la suivante :

Si la condition est une chaîne vide ou une espace, elle sera alors considérée comme fausse et &lt;sinon texte2> sera renvoyé. Sinon, c'est &lt;alors texte1> qui est renvoyé. Le &lt;sinon texte2> peut être omis, dans ce cas le résultat retourné sera vide si la condition est fausse.

Un exemple, (si le #if est utilisé dans le code de « Modèle » avec « paramètre » présent, vide ou absent) : en tapant : |                       \______________/                                      |                               |                                      _|_                             _|_

Prenez note que la fonction <tt>if</tt> ne connait pas le signe « = » ni les expressions mathématiques. renverra « oui » car la chaîne « 1 = 2 » n'est pas vide. Elle est prévue en tant que structure if définie. Pour comparer des chaînes, utilisez <tt>ifeq</tt>. Pour comparer des nombres, utilisez <tt>ifexpr</tt>.

Exemples :

->

->

->

->

->

->

->

#ifeq:
<tt>#ifeq:</tt> compare deux chaînes et retourne une autre chaîne selon le résultat de la comparaison. La syntaxe est la suivante :

#iferror:
Cette function prend un paramètre chaîne en entrée et retourne un des résultats fournis dans un ou deux paramètres suivants ; la fonction évalue le premier paramètre comme vrai si la chaîne donnée en entrée contient un objet HTML ayant la <tt>class="error"</tt>, qui est générée par d’autres fonctions de parseur telles que <tt>#expr:</tt>, <tt>#time:</tt> et <tt>#rel2abs:</tt>, des erreurs de modèles telles que des boucles et récursions, et d’autres erreurs de parseur à erreur non fatale.


 * <tt> </tt>

L’une ou l’autre des chaînes de retour peut être omise :
 * Si la valeur retournée si erreur est omise, la fonction retournera une chaine vide en cas d’erreur détectée dans la chaîne testée.
 * Sinon si la valeur retournée si correcte est omise, la chaîne testée sera retournée simplement si elle n’est pas erronée.


 * <tt> </tt> →  
 * <tt> </tt> →  
 * <tt> </tt> →  
 * <tt> </tt> →  
 * <tt> </tt> →  
 * <tt> </tt> →  
 * <tt> </tt> →  

#ifexist:
retourne une chaîne selon l'existence ou non d'une page.

ne gère pas les chemins relatifs (comme '../foo') ; pour cela, l'utiliser en combinaison avec.

#switch:
compare une valeur unique à plusieurs autres et renvoie une chaîne si une correspondance est trouvée. La syntaxe est principalement :

cherchera à travers toutes les valeurs jusqu'à ce qu'une correspondance soit trouvée. Lorsque la correspondance est trouvée, le résultat pour cette valeur est renvoyée (la chaîne de texte après le signe égal). Si aucune correspondance n'a été trouvée, le dernier résultat trouvé n'ayant pas de signe égal sera renvoyé comme texte par défaut. Si votre résultat par défaut doit comporter un signe égal, vous devez utiliser  :

Notez qu’il est également possible d'avoir une « dégringolade » de valeurs (qui réduit la nécessité de résultats dupliqués). Par exemple :

Notez la façon dont les valeur1 et valeur2 n'ont pas de signe égal. Si elles entrent en correspondance, elles auront alors le résultat de la valeur3 (c'est-à-dire que nous aurons le résultat3).

En revanche (comme aussi le  de nombreux langages de programmation), le code suivant ne pourra pas retourner plusieurs résultats simultanément :

Ci-dessus, quand la &lt;valeur à comparer&gt; est &lt;valeur1&gt;, le résultat sera &lt;résultat1&gt; seulement (et les branches suivantes seront ignorées). Si plusieurs résultats doivent être retournés, il faut soit employer un deuxième, soit combiner les résultats multiple dans la même branche. Le  ne permet pas non plus la continuation d’une branche à l’autre.

#time:
La fonction parseur <tt>#time:</tt> évalue l'heure courante sur le serveur (UTC sur les sites de la fondation WikiMedia). Son paramètre est une chaîne de format, dont certaines lettres sont reconnues pour générer un champ basé sur l'heure actuelle, les autres caractères de la chaîne étant conservés verbatim dans le résultat (ces chaînes de format sont identiques à celles supportées dans le langage de programmation PHP utilisé sur le serveur). Les valeurs non numériques retournées dépendent de la la locale du serveur (langue, conventions locales de dates et heures, fuseau horaire), en anglais et à l'heure UTC sur le serveur Meta de WikiMedia :

(explication des champs à compléter)

#timel:
Même chose que la fonction parseur <tt>#time:</tt> (avec les mêmes paramètres) mais cette fois utilise l’heure et la date locale sur le serveur (selon sa locale par défaut et non l’heure et la date UTC).

#rel2abs:
convertit un chemin relatif en un chemin absolu.

Un chemin relatif est un chemin commençant par '/', './', '../', contenant '/../' ou '/.', ou est simplement la chaîne '..' ou '.'. Si un chemin de base est donné, il doit être défini de façon absolue.

subst:
L'emploi de <tt>subst:</tt> à une fonction du parseur fonctionne, à condition qu'il n'y ait aucun espace entre « subst: » et « # ». Voir également la substitution récursive optionnelle.

Tableaux
Actuellement, la syntaxe du pipe des tableaux du wiki ne fonctionne pas au sein des conditionnelles, il y a deux moyens de contourner le problème :
 * cacher le pipe de la fonction parseur en le mettant dans un modèle, par exemple |
 * utiliser la syntaxe html des tableaux à la place (solution préférable dans le code des modèles).

Installation
Ne concerne que ceux qui ont installé un autre wiki sur leur propre site et désirent intégrer cette fonction. Ouvrez le dépôt SVN listant les branches de codes à l'adresse suivante :http://svn.wikimedia.org/viewvc/mediawiki/branches/ et cliquez sur la branche correspondant à la version de votre MediaWiki Par exemple, si la version du logiciel MediaWiki que vous avez installée est 1.15.x, cliquez sur REL1_15/

Cliquez ensuite sur la branche "extensions/" puis sur la branche "ParserFunctions/" Il va falloir copier les fichiers dans un nouveau répertoire appelé ParserFunctions, dans votre répertoire extensions.
 * Expr.php
 * ParserFunctions.php
 * ParserFunctions.i18n.php
 * ParserFunctions.i18n.magic.php

Pour copier un de ces fichiers, cliquez sur le numéro de la colonne Rev. faisant face au nom du fichier puis sur le lien "download" en haut de la page ainsi accédée. Il ne reste plus qu'à copier le fichier en cliquant dans le menu "Fichier/enregistrer sous" de votre navigateur

Ensuite, placez le texte suivant à la fin de votre LocalSettings.php :

require_once( "$IP/extensions/ParserFunctions/ParserFunctions.php" );

1.6
La plupart des ParserFunctions (à l'exception de #if, qui ne fonctionne pas du tout) fonctionnent aussi bien dans MediaWiki 1.6, mais la syntaxe des ParserFunctions est précédée du caractère '#'. Si vous voulez ajouter le caractère '#', recherchez cette partie du code dans ParserFunctions.php: $wgParser->setFunctionHook( 'expr', array( &$wgExtParserFunctions, 'expr' ) ); $wgParser->setFunctionHook( 'if', array( &$wgExtParserFunctions, 'ifHook' ) ); $wgParser->setFunctionHook( 'ifeq', array( &$wgExtParserFunctions, 'ifeq' ) ); $wgParser->setFunctionHook( 'ifexpr', array( &$wgExtParserFunctions, 'ifexpr' ) ); $wgParser->setFunctionHook( 'switch', array( &$wgExtParserFunctions, 'switchHook' ) );

Puis, replacez avec ce code :

$wgParser->setFunctionHook( '#expr', array( &$wgExtParserFunctions, 'expr' ) ); $wgParser->setFunctionHook( '#if', array( &$wgExtParserFunctions, 'ifHook' ) ); $wgParser->setFunctionHook( '#ifeq', array( &$wgExtParserFunctions, 'ifeq' ) ); $wgParser->setFunctionHook( '#ifexpr', array( &$wgExtParserFunctions, 'ifexpr' ) ); $wgParser->setFunctionHook( '#switch', array( &$wgExtParserFunctions, 'switchHook' ) );

Voir aussi

 * Help:Extension:ParserFunctions pour une aide plus détaillée et à jour ;
 * Extension:StringFunctions ;
 * Extension:DynamicFunctions ;
 * Extension:VariablesExtension.

Liens externes

 * The discussion about the ParserFunctions in the Wikitech-l list archive
 * meta:Category:Templates using ParserFunctions
 * en:Category:Templates using ParserFunctions