Paramètres et Séquences
Il est important de noter la relation entre les paramètres et les séquences, et comment les paramètres et les séquences sont utilisées dans l’expression XPath. Nous utilisons les définitions suivantes pour rendre ces relations plus claires :
•Une séquence consiste en éléments qui sont soit des valeurs atomiques ou des nœuds. Une virgule peut être utilisée pour construire une séquence, en la plaçant entre les éléments d’une séquence et permettant ainsi à la séquence d’être construite.
•Une fonction XPath peut être définie pour prendre les paramètres. Par exemple, dans l’expression XPath 2.0 count($a), la partie à l’intérieur des parenthèses de la fonction est le paramètre de la fonction et doit être une séquence d’éléments.
•Un argument consiste en un ou plusieurs items dans l’appel de la fonction. Par exemple, la fonction count(//Person) a un argument : //Person. Cet argument est valide car il renvoie une séquence de nœuds, qui correspond à la signature de la fonction count(). (La signature d’une fonction spécifie le nombre de paramètres et le type de données prévu pour chaque paramètre. Elle spécifie aussi ce que la fonction retournera et le type de données de l’objet retourné)
•La fonction substring('StyleVisionExamples', 6, 6)- qui retourne le string Vision—a trois arguments. Ceci est valide conformément à la signature de la fonction substring(), et est spécifié par celle-ci. Lorsqu’un appel de fonction a de multiples arguments, ceux-ci sont séparés par des virgules.
Parenthèses comme délimiteurs de séquence
Un point clé à noter lorsque des expressions XPath sont créées est ceci : Les parenthèses sont utilisées pour délimiter les séquences qui utilisent le séparateur ou l’opérateur d’intervalle pour énumérer les séquences. En guise de résultat, chaque séquence délimitée par les parenthèses est lue comme un paramètre (dans les définitions de la fonction) ou comme un argument (dans les appels de fonction).
Les parenthèses ne sont pas nécessaires autour d’une expression chemin (ou localisateur), (exemple d’une expression chemin : //Person/@salary), car une expression chemin peut être lue de manière non ambigüe comme un paramètre ou un argument. Il s’agit en fait d’un paramètre/argument à une séquence.
Vous trouverez ici quelques exemples pour illustrer les points réalisés ci-dessus :
•avg((10, 20, 30)) La avg fonction de XPath 2.0 prend une séquence d’items comme seul argument. Puisque cette séquence est une énumération séparée par une virgule, la paire intérieure de parenthèses est nécessaire pour délimiter la seule séquence obligatoire. Sans les parenthèses intérieures, l’argument aurait trois arguments et serait invalide pour cette raison. (La paire extérieure de parenthèses est la parenthèse de la fonction.)
•avg(//Person/@salary) Cette expression chemin sélectionne les nœuds attribut salary de tous les éléments Person et retourne leurs valeurs attribut comme séquence à évaluer (c’est-à-dire, pour établir une moyenne). Aucune parenthèse n’est requise car la séquence n’est pas énumérée avant que l’argument ne soit lu. L’argument est la seule expression chemin (ou localisateur). L’expression chemin est évaluée et les valeurs retournées sont soumises à la fonction comme items d’une séquence.
•count((10 to 34)) Ceci est une énumération via l’opérateur d’intervalle. L’opérateur d’intervalle 'to' génère une séquence d’items séparés par une virgule (les entiers de 10 à 34) avant que l’argument ne soit lu. En guise de résultat, la fonction count() a une séquence séparée par une virgule de 25 items à l’intérieur de son argument. Pour lire ceci comme argument à une seule séquence, il est nécessaire de délimiter les parenthèses comme requis. Sans de telles parenthèses, l’appel de fonction aurait 25 arguments à la place d’une—invalidant ainsi l’appel de fonction, puisque la fonction count() doit, selon sa signature, avoir uniquement un argument.
•Count((10(10 à 34, 37)) Les parenthèse intérieures indiquent que tout à l’intérieur d’elles est le seul argument de l’appel de fonction—une seule séquence consistant en 26 items.
•count(//Person) Aucune parenthèse de délimitation de séquence n’est requise autour d’un seul argument. L’argument est une expression chemin qui collecte les nœuds //Person dans le document XML et retourne ces nœuds comme les items de la séquence à compter.
Utiliser les paramètres XPath dans les fonctions XPath
Quand les paramètres sont utilisés dans la définition d’une fonction XPath définie par l’utilisateur, assurez-vous (i) qu’un nombre d’arguments dans l’appel de la fonction vers cette fonction XPath définie par l’utilisateur est correcte, et (ii) que les arguments évaluent correctement ce type et l’occurrence prévus.
La capture d’écran ci-dessus définit trois paramètres (dans le volet Paramètres), puis utilise ces paramètres (dans le volet Corps de fonction) pour définir une fonction XPath.
Chaque paramètre qui est défini dans les Parameters peut être considérée être une seule séquence. Le nombre d’items autorisés à l’intérieur d’une seule séquence est spécifiée avec la propriété Occurrence. Dans la définition ci-dessus, chaque paramètre est défini (dans sa propriété Occurrence) comme une séquence simple (à savoir, une séquence d’exactement un élément). Chaque argument de l’appel de fonction doit donc en être une séquence d’un seul item. Cette propriété Type spécifie le type de données des items de la séquence.
Dans la définition de notre fonction XPath (dans le volet Function Body), chaque paramètre fournit un item de la séquence pour définir une moyenne. Puisque les paramètres XPath constituent ensemble une séquence, la séquence doit être entre parenthèses pour assurer que toute la séquence est lue comme le paramètre de la fonction avg(). Si, lors de l’exécution, un des arguments dans l’appel de fonction (correspondant aux trois paramètres) n’est pas une séquence singleton (simple), une erreur est retournée.
Ci-dessous, vous trouverez des exemples de l’utilisation du paramètre XPath dans les appels vers la fonction XPath ThreeAverage() affichée dans la capture d’écran ci-dessus. Dans le Mode Design, vous pouvez insérer un calcul automatique et lui donner les expressions XPath rencensées ci-dessous pour voir les résultats. La fonction a été définie pour prendre une séquence de trois entiers et en définir une moyenne..
•sps:ThreeAverage(10,20,30) retourne 20. Il existe trois arguments valides dans l’appel de la fonction, correspondant aux trois paramètres XPath.
•sps:ThreeAverage( (10),(20),(30) ) retourne 20. Il existe trois arguments d’entrée valides, correspondant aux trois paramètres XPath. Chaque argument d’entrée a été enveloppé de parenthèses (qui sont redondants, puisque chaque séquence est une séquence singleton ; toutefois, cette redondance n’est pas une erreur).
•sps:ThreeAverage( (10),20,30 ) retourne 20. Il existe trois arguments d’entrée valides, correspondant aux trois paramètres XPath. Le premier argument a été enveloppé de parenthèses (redondant, mais pas une erreur).
•sps:ThreeAverage( (10,20),(30),(40) ) retourne une erreur car le premier argument n’est pas valide. Il ne s’agit pas d’une séquence singleton, tel que requis par la définition du premier paramètre $a ('Exactly one').
•sps:ThreeAverage( (10,20,30) ) retourne une erreur car seul un argument d’entrée est soumis, à l’intérieur des parenthèses. Par ailleurs, l’argument est invalide car la séquence n’est pas une séquence singleton.
Si la propriété Occurrence d’un paramètre est définie comme At-least-one (comme dans la définition affichée dans la capture d’écran ci-dessous), alors ce paramètre est défini comme séquence d’un-ou-plus d’items.
Dans la définition ci-dessus, le premier paramètre a été défini comme séquence d’un ou plusieurs items, les deux prochains paramètres comme séquences singleton. La fonction a été définie pour compter le nombre d’items soumis par le premier paramètre, ajouter le résultat de la somme des deux entiers soumis par les deux autres paramètres, puis diviser le résultat par trois pour obtenir la moyenne. Veuillez noter les points suivants :
•La séquence qui est le paramètre de la fonction avg() est enveloppée entre parenthèses. Ceci est fait pour spécifier que la fonction avg() prend une seule séquence consistant en trois items comme son paramètre. La seule séquence consiste en trois entiers : le premier soumis par la fonction count() ; le deuxième et le troisième sont les deux paramètres b et c.
•L’argument de la fonction count() n’est pas entre parenthèses de la délimitation de séquence car l’argument est une seule séquence explicite.
Ci-dessous, vous trouverez des exemples de l’utilisation du paramètre dans les appels vers la fonction XPath Average() affichée dans la capture d’écran ci-dessus.
•sps:Average((1,2),3,4) returns 3. Il existe trois arguments d’entrée valides, correspondant aux trois paramètres. Le premier argument est entre parenthèses pour le délimiter. Lorsque la fonction count() opère sur celui-ci, la fonction retournera la valeur 2, qui sera le premier item de la séquence soumise à la fonction avg().
•sps:Average( 4,4,4 ) retourne 3. Il existe trois arguments d’entrée valides. Le premier argument est autorisé d’être une séquence d’un item (voir la propriété Occurrence de son paramètre correspondant). Aucune parenthèse n’est requise pour indiquer les arguments séparés.
Points d’intérêt supplémentaires
Les points supplémentaires suivants devraient être notés :
•Si un paramètre est défini comme ayant une occurrence At-least-one, alors une fonction telle que MyAverage() pourrait être définie avec une expression XPath telle que avg(($a)). Cette fonction accepterait un argument qui est une seule séquence d’un-ou-plus d’items. La fonction pourrait être appelée comme suit : sps:MyAverage((2,3,4)), et elle retournerait la valeur 3. L’argument d’entrée doit être entre parenthèses pour assurer que l’entrée est lue comme une séquence unique plutôt que de trois séquences singleton (qui serait le cas s’il n’y avait pas de parenthèses enveloppantes).
•Si un paramètre XPath $a est défini ayant une occurrenceNone-or-one, alors une fonction telle que MyAverage() pourrait être définie avec une expression XPath telle que avg(($a, $b, $c)). Cette fonction accepterait trois séquences comme son argument, avec la possibilité de la première séquence étant vide. Si la première séquence est vide, alors une séquence vide doit soumettre explicitement comme premier argument d’entrée. Autrement une erreur est reportée. Si la fonction était appelée comme suit : sps:MyAverage(30,20,10), elle retournerait la valeur 20. La fonction pourrait aussi être appelée avec: sps:MyAverage((),20,10), retournant 15 (notez que la séquence vide compte : comme valeur d’entrée de vide ; pour une valeur retour de 10, le premier item devrait être 0). Toutefois, ce qui suit générerait une erreur : sps:MyAverage(20,10), car aucune séquence vide n’est fournie et, en conséquence, le troisième argument d’entrée est considéré être absent.
Exemples complexes
Outre le fait d’avoir l’avantage d’être capable de réutiliser une expression XPath, les fonctions XPath définies par l’utilisateur peuvent aussi activer la construction de fonctions XPath complexes personnalisées qui ne sont pas disponibles dans l’ensemble de la fonction XPath 2.0. Par exemple, une fonction factorielle pourrait facilement être créée avec une expression XPath qui prend une séquence singleton comme son seul paramètre. Si le paramètre $num est le nombre à factoriser, alors l’expression XPath à créer la fonction serait :
if ($num < 2) then 1 else $num * sps:Factorial($num - 1)
Si la fonction était appelée Factorial(), alors le factoriel, disons 6, pourrait être obtenu en appelant la fonction avec : sps:Factorial(6).