2.5. Segments (Segments)

2.5. Segments

Pour chaque nœud d'une nodelist d'entrée, les segments appliquent un ou plusieurs sélecteurs au nœud et concatènent les résultats de chaque sélecteur en nodelists par nœud d'entrée, elles-mêmes ensuite concaténées dans l'ordre de la nodelist d'entrée pour former une seule nodelist résultat du segment.

Il s'avère que plus il y a de segments dans une requête, plus la profondeur dans la valeur d'entrée des nœuds de la nodelist résultante est grande :

• Une requête avec N segments, où N >= 0, produit une nodelist constituée de nœuds à une profondeur dans la valeur d'entrée de N ou plus.

• Une requête avec N segments, où N >= 0, tous étant des segments enfants (section 2.5.1), produit une nodelist constituée de nœuds précisément à la profondeur N dans la valeur d'entrée.

Il existe deux types de segments : segments enfants et segments descendants.

segment             = child-segment / descendant-segment

La syntaxe et la sémantique de chaque type de segment sont définies ci-dessous.

2.5.1. Child Segment (Segment enfant)

2.5.1.1. Syntax (Syntaxe)

Le segment enfant consiste en une séquence non vide de sélecteurs séparés par des virgules, entre crochets.

Des notations abrégées sont aussi fournies lorsqu'il n'y a qu'un seul sélecteur joker ou de nom.

child-segment       = bracketed-selection /
                      ("."
                       (wildcard-selector /
                        member-name-shorthand))

bracketed-selection = "[" S selector *(S "," S selector) S "]"

member-name-shorthand = name-first *name-char
name-first          = ALPHA /
                      "_"   /
                      %x80-D7FF /
                      %xE000-10FFFF
name-char           = name-first / DIGIT

DIGIT               = %x30-39
ALPHA               = %x41-5A / %x61-7A

., un segment enfant construit directement à partir d'un wildcard-selector, est l'abréviation de [].

.<member-name>, un segment enfant construit à partir d'un member-name-shorthand, est l'abréviation de ['<member-name>']. Note : Ceci n'est utilisable qu'avec des noms de membres composés de certains caractères, comme spécifié dans la règle ABNF member-name-shorthand. Ainsi, par exemple, $.foo.bar est l'abréviation de $['foo']['bar'] (mais pas de $['foo.bar']).

2.5.1.2. Semantics (Sémantique)

Un segment enfant contient une séquence de sélecteurs, chacun sélectionnant zéro ou plusieurs enfants de la valeur d'entrée.

Des sélecteurs de types différents peuvent être combinés dans un seul segment enfant.

Pour chaque nœud de la nodelist d'entrée, la nodelist résultante d'un segment enfant est la concaténation des nodelists de chacun de ses sélecteurs dans l'ordre où les sélecteurs apparaissent dans la liste. Note : Tout nœud correspondant à plus d'un sélecteur est conservé autant de fois dans la nodelist.

Lorsqu'un sélecteur peut produire une nodelist dans plus d'un ordre possible, chaque occurrence du sélecteur dans le segment enfant peut produire une nodelist dans un ordre distinct.

En résumé, un segment enfant s'enfonce d'un niveau de plus dans la structure de la valeur d'entrée.

2.5.1.3. Examples (Exemples)

JSON :

["a", "b", "c", "d", "e", "f", "g"]

Requêtes :

Requête	Résultat	Chemins	Commentaire
		de résultat
$[0,	"a"	$[0]	Indices
3]	"d"	$[3]
$[0:2,	"a"	$[0]	Tranche et
5]	"b"	$[1]	indice
	"f"	$[5]
$[0,	"a"	$[0]	Entrées
0]	"a"	$[0]	dupliquées

Tableau 15 : Exemples de segment enfant

2.5.2. Descendant Segment (Segment descendant)

2.5.2.1. Syntax (Syntaxe)

Le segment descendant consiste en un double point .. suivi d'un segment enfant (notation entre crochets).

Des notations abrégées correspondant aux formes abrégées du segment enfant sont aussi fournies.

descendant-segment  = ".." (bracketed-selection /
                            wildcard-selector /
                            member-name-shorthand)

.., le segment descendant construit directement à partir d'un wildcard-selector, est l'abréviation de ..[].

..<member-name>, un segment descendant construit à partir d'un member-name-shorthand, est l'abréviation de ..['<member-name>']. Note : Comme pour l'abréviation analogue du segment enfant, ceci n'est utilisable qu'avec des noms de membres composés de certains caractères, comme spécifié dans la règle ABNF member-name-shorthand.

Note : À lui seul, .. n'est pas un segment valide.

2.5.2.2. Semantics (Sémantique)

Un segment descendant produit zéro ou plusieurs descendants d'une valeur d'entrée.

Pour chaque nœud de la nodelist d'entrée, un sélecteur descendant visite le nœud d'entrée et chacun de ses descendants de sorte que :

• les nœuds de tout tableau sont visités dans l'ordre du tableau, et

• les nœuds sont visités avant leurs descendants.

L'ordre dans lequel les enfants d'un objet sont visités n'est pas prescrit, car les objets JSON sont non ordonnés.

Supposons que le segment descendant soit de la forme ..[<selectors>] (après conversion de toute forme abrégée en notation entre crochets), et que les nœuds, dans l'ordre de visite, soient D1, ..., Dn (où n >= 1). Note : D1 est la valeur d'entrée.

Pour chaque i tel que 1 <= i <= n, la nodelist Ri est définie comme le résultat d'appliquer le segment enfant [<selectors>] au nœud Di.

Pour chaque nœud de la nodelist d'entrée, le résultat du segment descendant est la concaténation de R1, ..., Rn (dans cet ordre). Ces résultats sont ensuite concaténés dans l'ordre de la nodelist d'entrée pour former le résultat du segment.

En résumé, un segment descendant s'enfonce d'un ou plusieurs niveaux dans la structure de chaque valeur d'entrée.

2.5.2.3. Examples (Exemples)

JSON :

{
  "o": {"j": 1, "k": 2},
  "a": [5, 3, [{"j": 4}, {"k": 6}]]
}

Requêtes :

(Notez que le quatrième exemple peut s'exprimer en deux requêtes équivalentes, montrées au tableau 16 sur une seule ligne au lieu de deux lignes presque identiques.)

Requête	Résultat	Chemins de résultat	Commentaire
$..j	1	$['o']['j']	Valeurs d'objet
	4	$['a'][2][0]['j']
$..j	4	$['a'][2][0]['j']	Résultat
	1	$['o']['j']	alternatif
$..[0]	5	$['a'][0]	Valeurs de tableau
	{"j": 4}	$['a'][2][0]
$..[*]	{"j": 1,	$['o']	Toutes les valeurs
ou	"k": 2}	$['a']
$..*	[5, 3,	$['o']['j']
	[{"j": 4},	$['o']['k']
	{"k": 6}]]	$['a'][0]
	1	$['a'][1]
	2	$['a'][2]
	5	$['a'][2][0]
	3	$['a'][2][1]
	[{"j": 4},	$['a'][2][0]['j']
	{"k": 6}]	$['a'][2][1]['k']
	{"j": 4}
	{"k": 6}
	4
	6
$..o	{"j": 1,	$['o']	La valeur d'entrée
	"k": 2}		est visitée
$.o..[*,	1	$['o']['j']	Ordre non déterministe
*]	2	$['o']['k']
	2	$['o']['k']
	1	$['o']['j']
$.a..[0,	5	$['a'][0]	Plusieurs segments
1]	3	$['a'][1]
	{"j": 4}	$['a'][2][0]
	{"k": 6}	$['a'][2][1]

Tableau 16 : Exemples de segment descendant

Note : L'ordre des résultats pour les exemples $..[] et $.. ci-dessus n'est pas garanti, sauf que :

• {"j": 1, "k": 2} doit apparaître avant 1 et 2,

• [5, 3, [{"j": 4}, {"k": 6}]] doit apparaître avant 5, 3, et [{"j": 4}, {"k": 6}],

• 5 doit apparaître avant 3, qui doit apparaître avant [{"j": 4}, {"k": 6}],

• 5 et 3 doivent apparaître avant {"j": 4}, 4, {"k": 6}, et 6,

• [{"j": 4}, {"k": 6}] doit apparaître avant {"j": 4} et {"k": 6},

• {"j": 4} doit apparaître avant {"k": 6},

• {"k": 6} doit apparaître avant 4, et

• 4 doit apparaître avant 6.

L'exemple ci-dessus avec la requête $.o..[*, *] montre qu'un sélecteur peut produire des nodelists dans des ordres distincts à chaque fois qu'il apparaît dans le segment descendant.

L'exemple ci-dessus avec la requête $.a..[0, 1] montre que le segment enfant [0, 1] est appliqué à chaque nœud à tour de rôle (plutôt que les nœuds étant visités une fois par sélecteur, ce qui est le cas pour certaines implémentations JSONPath non conformes à cette spécification).