JSON
| JSON = class static (Object) | Interface de JSON | Exemples de JSON |
Qubes 6.1 Classe statique de manipulation de données JSON
Il s'agit d'une classe statique : on n'instancie pas d'objet de la classe JSON avec un constructeur.
Par contre, on peut utiliser les méthodes de cette classe en les préfixant par "JSON." quand on les utilise.
Le JSON est un format de représentation des données.
Il y a des types de base (string, number, true/false, null) qui peuvent être structurés en tableaux (array) ou en objets (object).
Un tableau ou un objet peut lui-même contenir des tableaux ou des objets.
En script, une structure JSON peut être représentée par une variable de type JSONVariant. La classe JSON permet de manipuler ces variables JSONVariant :
- création d'un JSONVariant à partir d'une chaîne de caractères : JSON.Parse
- création d'une chaîne de caractères à partir d'un JSONVariant : JSON.Stringify
- création d'un JSONVariant qui représente un tableau JSON : JSON.NewArray
- création d'un JSONVariant qui représente un objet JSON : JSON.NewObject
Quand on a un JSONVariant qui représente un tableau, on peut :
- ajouter/modifier des items dans le tableau via un index : myJSON[index]:=myValue;
- ajouter via Add()/Push(): myJSON.Add(1, 2, 3)
- supprimer un élément avec Delete(index) : myJSON.Delete(2) (Qubes 7.2)
- echanger deux éléments avec Swap(index1, index2) : myJSON.Swap(0,2) (Qubes 7.2)
Quand on a un JSONVariant qui représente un objet, on peut :
- ajouter/modifier des propriétés de l'objet via leur nom : myJSON[nom]:=myValue;
- si le nom est compatible avec la syntaxe des indicateurs Pascal (pas d'espace, ne commence pas par un chiffre), on peut directement l'utiliser comme une propriété d'objet : myJSON.nom:=myValue;
- supprimer une propriété par son nom: myJSON.Delete('nom') (Qubes 7.2)
Pour les tableaux et les objets les méthodes suivantes sont aussi disponibles:
- .Length() : nombre d'éléments
- .Low() & .High() : indices bas et haut des éléments
- .Defined() : retourne True si l'élément n'est pas Undefined, équivalent à "not VarIsClear" (Qubes 8.0)
- .ElementName(index) : retourne le nom de l'élément d'indice donné
- .TypeName() : nom du type de l'objet JSON (Undefined, Null, Object, Array, String, Number ou Boolean)
- .Clone() : clone le JSONVariant
- .AddFrom() : pour un tableau, transfert les éléments du tableau passé en paramètre et les ajoute à la fin du tableau (Qubes 10.0)
- .Extend() : étend le JSONVariant, pour un objet remplace ou ajoute les champs nommés par des clones, pour un tableau, ajoute des clones des éléments (Qubes 10.0)
Les parenthèses () sont requises, sans quoi ce sera le champ qui sera accédé (champ "Length", "Low", etc.)
Les types de base des scripts Qubes peuvent directement être affectés à un JSONVariant car ils sont compatibles (NB : il y a aussi une constante Null en script).
Performance: Le type JSONVariant est une abstraction de type DOM (Document Object Model), son encombrement mémoire est bien plus important que le JSON qu'il représente (un ordre de grandeur ou plus), et il y a un coût CPU significatif à la manipulation de DOM complexes. Pour les méthodes de sérialisation, il est ainsi préférable d'utiliser et de manipuler des representations chaînes du JSON dès que possible.
Note: les JSONVariant respectent un single-ownership, ie. une instance de JSONVariant peut être rattachée au plus à un seul autre JSONVariant (cf. exemple single-ownership). Cette contrainte permet d'éviter les boucles récursives, mais a pour effet qu'il n'est pas possible de référencer une même instance dans deux structures distinctes.
Dans la grand majorité des cas cette contrainte ne sera pas limitante, les JSONVariant étant destinés aux entrées/sorties et non à la gestion de de structures auto-référentes en mémoire. Par contre l'absence de possibilité de récursion signifie qu'ils peuvent être utilisés sans avoir à mettre en place des protections logiques anti-boucles infinies dans le code.
Dans la v10, la ré-affectation d'un JSONVariant à un autre JSONVariant ne provoque pas d'erreur : cela supprime le sous-élément du JSONVariant précédent auquel il était affecté (suppression de l'élément en cas d'un tableau ou de la propriété en cas d'un objet).
Cf. Exemples.