json — `n_pbt_json` #

← Référence des composants · Sommaire du guide

Construire un JSON type par type — texte, nombre, booléen, tableau, objet imbriqué — avec l'échappement fait pour vous, puis en relire un le long d'un chemin : of_load, of_get_string, of_type, of_count. Un seul objet bâtit vos requêtes et lit vos réponses. Tout en PowerScript pur : aucune page, aucun moteur, PowerBuilder 10 compris.

▶ Le voir en vrai — Application de démonstration, tuile JSON : les résultats, le code qui les produit et cette page, côte à côte.

En bref #

n_pbt_json est autoinstantiate : on le déclare en variable locale, sans create ni destroy. C'est le même objet qui sert, en interne, à bâtir les charges utiles envoyées au moteur — désormais offert à votre code, côté construction et lecture.

Démarrage rapide #

Bâtir une charge utile, puis relire une réponse — tout tient dans une variable locale :

n_pbt_json  lnv_json
string      ls_customer
double      ld_total

// Write : each member is typed and escaped for you - a path may have levels
lnv_json.of_set_string("customer", "Ada")
lnv_json.of_set_number("total", 690.50)
lnv_json.of_set_boolean("paid", true)
// lnv_json.of_text() -> {"customer":"Ada","total":690.5,"paid":true}

// Read : load a response, reach values by path
lnv_json.of_load('{"order":{"customer":"Ada","total":690.50}}')
IF lnv_json.of_is_valid() THEN
	ls_customer = lnv_json.of_get_string("order/customer")   // Ada
	ld_total    = lnv_json.of_get_number("order/total")     // 690.5
END IF

Un chemin est la suite des clés depuis la racine, jointes par / ; l'index d'un tableau est sa position, comptée à partir de 0 : order/lines/0.

Construire une charge utile #

Méthode	Rôle
`of_add_string (string as_path, string as_value) → long`	Ajoute une CHAÎNE, échappée pour vous, au TABLEAU situé à `as_path`. Le tableau doit exister : ouvrez-le d'abord avec `of_set_raw` et un tableau vide. Rend `0`, `-4` si `as_path` est absent ou n'est pas un tableau
`of_add_boolean (string as_path, boolean ab_value) → long`	Ajoute un BOOLÉEN (`true` ou `false`, jamais entre guillemets) au TABLEAU situé à `as_path`. Le tableau doit exister : ouvrez-le d'abord avec `of_set_raw` et un tableau vide. Rend `0`, `-4` si `as_path` est absent ou n'est pas un tableau
`of_add_number (string as_path, long al_value) → long`	Ajoute un NOMBRE (trois surcharges : `integer`, `long`, `double`) au TABLEAU situé à `as_path`. Le tableau doit exister : ouvrez-le d'abord avec `of_set_raw` et un tableau vide. Rend `0`, `-4` si `as_path` est absent ou n'est pas un tableau
`of_add_raw (string as_path, string as_json) → long`	Ajoute une valeur DÉJÀ en JSON (un objet, un tableau) dont vous répondez au TABLEAU situé à `as_path`. Le tableau doit exister : ouvrez-le d'abord avec `of_set_raw` et un tableau vide. Rend `0`, `-4` si `as_path` est absent ou n'est pas un tableau
`of_set_array (string as_path, string as_values[]) → long`	ÉCRIT un TABLEAU entier de chaînes à `as_path` depuis un tableau PowerBuilder, chaque élément échappé. Un tableau vide en écrit un vide. Même règle de chemin et mêmes codes que `of_set_string`
`of_set_members (string as_fragment) → long`	Fusionne à la RACINE des membres déjà formés ailleurs, joints par des virgules. Un fragment vide n'écrit rien. Rend `0`
`of_clear ( )` → `long`	Vide le document pour recommencer un autre objet avec la même variable. Rend `0`
`of_text ( )` → `string`	Le document tel quel (compact) : ce que vous avez bâti (`of_add_string`, `of_add_number`...) ou chargé (`of_load`), après toute modification — la sortie unique, prête à envoyer, stocker ou réécrire. `of_pretty` en donne la forme indentée. `{}` si vide ; l'appeler ne vide rien

Lire un document #

Méthode	Rôle
`of_load (string as_json)` → `long`	Charge un texte JSON pour la lecture. Rend `0` s'il est bien formé, `-5` si l'argument est vide, `-4` s'il n'est pas du JSON valide (le document est alors abandonné). Analyse en PowerScript pur
`of_is_valid ( )` → `boolean`	Vrai quand le dernier `of_load` a réussi
`of_exists (string as_path)` → `boolean`	Vrai quand une valeur existe au chemin donné — distingue une valeur présente mais vide d'une valeur absente
`of_type (string as_path)` → `string`	Le type JSON au chemin : `object`, `array`, `string`, `number`, `boolean`, `null` ; vide si absent
`of_get_string (string as_path)` → `string`	La valeur au chemin, en texte : une chaîne décodée, un nombre/booléen/null en texte, un objet ou tableau en JSON brut (rechargeable par `of_load`)
`of_get_number (string as_path)` → `double`	Le nombre au chemin, en `double` — le point décimal est honoré sur toute machine (2.5 vaut 2,5, pas 2). `0` si absent
`of_get_boolean (string as_path)` → `boolean`	Le booléen au chemin : vrai seulement pour le littéral JSON `true`
`of_count (string as_path)` → `long`	Le nombre de membres de l'objet, ou d'éléments du tableau, au chemin. Rend `-1` si la valeur est scalaire ou absente (distingue un tableau vide, `0`, d'un absent, `-1`)
`of_name (string as_path, long al_index)` → `string`	Le nom du membre n° `al_index` (à partir de 1) de l'objet au chemin — pour lire les clés d'un objet dont on ignore la forme. Avec `of_count`, on parcourt l'objet
`of_pretty ( )` → `string`	Le document chargé, ré-indenté pour la lecture (plusieurs lignes, tabulations) — un log, une zone de texte. Vide si rien de valide n'est chargé

Modifier un document #

Le côté écriture change le document chargé sur place, puis of_text en rend le résultat (compact) — ce qu'on réécrit. Les setters remplacent la valeur au chemin, ou ajoutent la dernière clé quand elle manque à un objet parent. Chacun rend 0, -4 quand le parent manque ou n'est pas du bon type, -5 sur un chemin vide.

Membre	Rôle
`of_set_string (string as_path, string as_value) → long` → `long`	ÉCRIT une chaîne à `as_path`, échappée pour vous. Le chemin peut avoir PLUSIEURS niveaux (`a/b/c`) : les niveaux absents sont créés en OBJETS, et un document VIDE en devient un — écrire, c'est bâtir. Une valeur déjà là est remplacée, où qu'elle soit. Rend `0`, `-4` si un niveau du chemin est un scalaire ou un tableau, `-5` sur un chemin vide
`of_set_number (string as_path, long al_value) → long` → `long`	ÉCRIT un NOMBRE à `as_path`, le point décimal forcé quelle que soit la région. Trois surcharges : `integer`, `long`, `double`. Même règle de chemin et mêmes codes que `of_set_string`
`of_set_boolean (string as_path, boolean ab_value) → long` → `long`	ÉCRIT un BOOLÉEN à `as_path` : `true` ou `false`, jamais entre guillemets. Même règle de chemin et mêmes codes que `of_set_string`
`of_set_raw (string as_path, string as_json) → long` → `long`	ÉCRIT à `as_path` une valeur DÉJÀ en JSON — un objet imbriqué, un tableau, `null` — telle quelle : vous en répondez. C'est aussi ainsi qu'on OUVRE un tableau avant `of_add_*`. Même règle de chemin et mêmes codes que `of_set_string`
`of_remove (string as_path)` → `long`	Retire la valeur au chemin — un membre d'objet (sa clé et une virgule partent avec) ou un élément de tableau ; le résultat reste valide

n_pbt_json  lnv_json

// Load, edit in place, then read back the ONE document with of_text
lnv_json.of_load('{"name":"Ada","active":false}')
lnv_json.of_set_string("name", "Grace")   // replace
lnv_json.of_set_boolean("active", true)
lnv_json.of_set_number("count", 3)        // added : the key was absent
// lnv_json.of_text() -> {"name":"Grace","active":true,"count":3}

Portée. JSON s'analyse en PowerScript pur, sans page ni moteur : n_pbt_json reste autoinstantiate et fonctionne partout, PowerBuilder 10 compris. Pour du XML, voyez xml (qui s'appuie sur le moteur) ; pour afficher un JSON en arbre repliable, voyez jsontree.