Paramètres dans les fonctions XPath
Une fonction XPath définie par l’utilisateur peut être assignée à tout nombre de paramètres. Les paramètres de la fonction sont définis dans le volet Paramètres du dialogue des fonctions XPath (voir la capture d’écran ci-dessous). Ces paramètres peuvent être utilisés dans la définition de la fonction XPath définie par l’utilisateur (dans le volet Corps de fonction).
Mécanisme de fonction XPath défini par l’utilisateur
Les étapes ci-dessous expliquent comment la fonction XPath fonctionne.
1.Dans un appel de fonction (par exemple, dans un calcul automatique), le nombre d’arguments dans l’appel de la fonction doit correspondre au nombre de paramètres définis pour la fonction définie par l’utilisateur (tel que défini dans le volet Paramètres de la fonction définie par l’utilisateur ; voir la capture d’écran ci-dessous). De plus, le nombre d’items soumis par chaque argument (dans l’appel de fonction) doit correspondre à la définition Occurrence du paramètre correspondant. Si la restriction du type de données a été spécifiée pour un paramètre (dans la colonne Type d u volet Paramètres), la/les valeur/s soumise/s par l’argument doit correspondre à ce type de données.
2.Les arguments passés aux paramètres de la fonction sont ensuite utilisés dans la fonction XPath (comme défini dans le volet Corps de fonction ; voir la capture d’écran ci-dessous). Le résultat obtenu en évaluant l’expression XPath est ensuite vérifié par rapport à la définition optionnelle Type de retour (voir la capture d’écran ci-dessous). Si le type de données est comme attendu, le résultat est utilisé dans l’expression XPath de la laquelle la fonction a été appelée.
Ordre des paramètres
L’ordre des paramètres de la fonction définie par l’utilisateur est important car, lorsque la fonction est appelée, les arguments soumis dans la fonction seront attribués aux paramètres selon l’ordre dans lequel ils sont définis dans le volet Paramètres (voir la capture d’écran ci-dessous).
Donc si la fonction XPath sps:Stock définie par l’utilisateur est définie dans la capture d’écran ci-dessus et si elle est appelée avec l’expression XPath suivante:
sps:Stock($XML, Node1, Node2)
, alors ces trois arguments—$XML, Node1, Node2— seront attribués, dans cet ordre, respectivement, aux paramètres $ContextStock, $Selection et $StockInfo.
Notez que chaque argument dans l’appel de fonction est séparé du prochain par une virgule. Donc, chaque argument, tel que délimité par les virgules dans l’appel de fonction, sera passé au paramètre correspondant (tel que trié dans le volet Paramètres ; voir la capture d’écran ci-dessus).
L’ordre des paramètres dans le volet Paramètres peut être contrôlé avec les icônes Ajouter, Insérer et Supprimer du volet Paramètres.
Type de données des paramètres
En option, les types de données des paramètres de la fonction définie par l’utilisateur peuvent être définis. Si un type de données est spécifié, alors le type de données de l’argument entrant sera vérifié par rapport au type de données du paramètre, et une erreur sera retournée si les types ne correspondent pas. Cette fonction vous permet de vérifier les données d’entrée (depuis les arguments d’appel de la fonction).
Occurrence
Chaque paramètre de la fonction XPath définie par l’utilisateur peut être considérée être une séquence. La propriété Occurrence d’un paramètre spécifie comment de nombreux items doivent être soumis pour ce paramètre par l’argument correspondant de l’appel de fonction.
Dans les deux définitions de fonction et dans les appels de fonction, les virgules sont utilisées pour séparer un paramètre ou un argument d’un autre ainsi que des items séparés à l’intérieur d’une séquence. Pour cette raison, il est important de noter le contexte dans lequel la virgule est utilisée : pour séparer les paramètres/arguments ou pour séparer les items de séquence.
•Dans les paramètres/arguments, si requis, les parenthèses sont utilisées pour délimiter les séquences—dans la définition de fonction (paramètres) ou dans l’appel de fonction (arguments).
•Dans les séquences, les parenthèses sont ignorés.
Dans ce contexte, les exemples suivants et points devraient être notés :
•Parenthèses dans paramètres/arguments : Plusieurs fonctions XPath prennent une seule séquence comme argument, par exemple, les fonctions avg() et count(). Si cette séquence est énumérée utilisant des séparateurs ou opérateurs de gamme, la séquence doit être entre parenthèses pour montrer sans ambiguité qu’il s’agit d’une séquence simple—et non des séquences séparées par virgule multiples. Par exemple, dans la fonction avg((count($a), $b, $c)), la fonction XPath 2.0 avg() prend la séquence unique (count($a),$b,$c) comme son argument. Puisque les items de la séquence sont énumérés, faisant une séquence de trois items, la séquence doit être entre parenthèses et soumise comme un seul argument à la fonction: avg() avg((count($a),$b,$c)). Sans la paire intérieure de parenthèses, la définition de la fonction avg() aurait trois paramètres, et ceci serait une erreur (puisque la fonction avg() prévoit un argument consistant en une seule séquence).
•Aucune parenthèse dans paramètres/arguments : De manière semblable, las fonction count() prend également une seule séquence comme son argument un-paramètre. Toutefois, puisque dans notre exemple count($a), la seule séquence n’est pas une liste énumérée séparée par une virgule, mais est extraite à la place par la variable/le paramètre $a, l’argument n’a pas besoin d’être joint par un ensemble intérieur de parenthèses: Donc l’expression count($a) est correcte.
•Les parenthèses et virgules dans la fonction appellent : Dans un appel de fonction, les parenthèses doivent être correctement utilisées pour que chaque argument corresponde à un paramètre (tel que défini dans le volet Paramètres du dialogue des fonctions XPath). Par exemple, si une fonction XPath définie par l’utilisateur appelée MyAverage() est définie avec l’expression XPath 2.0: avg((count($a),$b,$c)), alors l’appel de fonction suivant pourrait être valide: MyAverage((1,2,3),4,5). Les valeurs correspondant aux trois paramètres $a, $b et $c seraient, respectivement, la séquence (1,2,3), la séquence simple 4, et la séquence simple 5. Des séquences simples peuvent, en option, être entre parenthèses. La valeur retournée par MyAverage() serait dans ce cas 4.