json — `n_pbt_json` #

← Komponentenreferenz · Inhalt des Handbuchs

JSON Typ für Typ bauen — String, Zahl, Boolean, Array, verschachteltes Objekt — mit dem Escaping für Sie erledigt, dann eines zurücklesen entlang eines Pfades: of_load, of_get_string, of_type, of_count. Ein einziges Objekt baut Ihre Anfragen und liest Ihre Antworten. Alles in reinem PowerScript: keine Seite, keine Engine, PowerBuilder 10 inbegriffen.

▶ Live ansehen — Demoanwendung, Kachel JSON: die Ergebnisse, der zugehörige Code und diese Seite nebeneinander.

Kurzüberblick #

n_pbt_json ist autoinstantiate: als lokale Variable deklarieren, ohne create oder destroy. Es ist genau das Objekt, das intern die an die Engine gesendeten Nutzdaten baut — jetzt Ihrem Code angeboten, auf der Bau- und der Leseseite.

Schnellstart #

Nutzdaten bauen, dann eine Antwort zurücklesen — alles passt in eine lokale Variable:

// Local variables
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(/*path*/ "customer", /*value*/ "Ada")
lnv_json.of_set_number(/*path*/ "total", /*value*/ 690.50)
lnv_json.of_set_boolean(/*path*/ "paid", /*value*/ true)

// lnv_json.of_text() -> {"customer":"Ada","total":690.5,"paid":true}

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

Ein Pfad sind die Schlüssel ab der Wurzel, verbunden mit /; ein Array-Index ist seine Position, ab 1 gezählt, wie jede Position der Bibliothek: order/lines/1 ist die erste Zeile, order/lines/0 bezeichnet nichts. Ein leeres Segment (a//b, /a) oder ein Index 0 auf einem Array bezeichnet nichts — ein Schreibvorgang lehnt es mit -5 ab — und ein Schlüssel, der ein / enthält, ist nicht adressierbar. Schreibt ein Objekt denselben Schlüssel zweimal, wird sein ERSTES Vorkommen gelesen und geschrieben — ein Browser behält das letzte.

Nutzdaten bauen #

Methode	Rolle
`of_add_string (string as_path, string as_value)` → `long`	Hängt eine ZEICHENKETTE, für Sie maskiert, an das ARRAY unter `as_path` an. Das Array muss vorhanden sein: öffnen Sie es zuerst mit `of_set_raw` und einem leeren Array. Liefert `0`, `-4`, wenn `as_path` fehlt oder kein Array ist, `-5`, wenn ein Segment von `as_path` leer oder ein Index 0 auf einem Array ist; eine Null-Zeichenkette wird leer geschrieben (für ein JSON-`null`: `of_add_raw(as_path, "null")`)
`of_add_boolean (string as_path, boolean ab_value)` → `long`	Hängt einen BOOLESCHEN Wert (`true` oder `false`, nie in Anführungszeichen) an das ARRAY unter `as_path` an. Das Array muss vorhanden sein: öffnen Sie es zuerst mit `of_set_raw` und einem leeren Array. Liefert `0`, `-4`, wenn `as_path` fehlt oder kein Array ist, `-5`, wenn ein Segment von `as_path` leer oder ein Index 0 auf einem Array ist; ein Null-Wert schreibt `null`
`of_add_number (string as_path, long al_value)` → `long`	Hängt eine ZAHL (fünf Überladungen: `integer`, `long`, `longlong`, `decimal`, `double` — ein `decimal` und ein `longlong` behalten ALLE Stellen (die Cent eines Betrags, die letzte Stelle einer ID über 2^53), und ein Literal wie `690.50` ist ein `decimal`, geschrieben `690.5`) an das ARRAY unter `as_path` an. Das Array muss vorhanden sein: öffnen Sie es zuerst mit `of_set_raw` und einem leeren Array. Liefert `0`, `-4`, wenn `as_path` fehlt oder kein Array ist, `-5`, wenn ein Segment von `as_path` leer oder ein Index 0 auf einem Array ist; ein Null-Wert schreibt `null`
`of_add_raw (string as_path, string as_json)` → `long`	Hängt einen Wert, der BEREITS JSON ist (ein Objekt, ein Array) und für den Sie einstehen an das ARRAY unter `as_path` an. Das Array muss vorhanden sein: öffnen Sie es zuerst mit `of_set_raw` und einem leeren Array. Liefert `0`, `-4`, wenn `as_path` fehlt oder kein Array ist, `-5`, wenn ein Segment von `as_path` leer oder ein Index 0 auf einem Array ist; ein leerer oder Null-Wert schreibt `null`. Der leere Pfad ist die WURZEL: `of_load("[]")` und dann `of_add_raw("", …)` baut ein Dokument, das ein Array ist (der Rumpf eines gebündelten API-Aufrufs). Viele Elemente nacheinander an dasselbe Array anzuhängen bleibt schnell
`of_set_array (string as_path, string as_values[])` → `long`	SCHREIBT ein ganzes ARRAY von Zeichenketten unter `as_path` aus einem PowerBuilder-Array, jedes Element maskiert. Ein leeres Array schreibt ein leeres, ein Null-Element eine leere Zeichenkette. Gleiche Pfadregel und gleiche Codes wie `of_set_string`
`of_set_members (string as_fragment)` → `long`	Führt bereits anderswo gebildete Mitglieder an der WURZEL zusammen, durch Kommas verbunden. Ein leeres Fragment schreibt nichts. Liefert `0`, `-4`, wenn die Wurzel des Dokuments kein Objekt ist
`of_clear ( )` → `long`	Leert das Dokument, um mit derselben Variablen ein anderes Objekt zu beginnen. Liefert `0`
`of_text ( )` → `string`	Das Dokument wie es ist (kompakt): das, was Sie gebaut (`of_add_string`, `of_add_number`...) oder geladen (`of_load`) haben, nach jeder Änderung — die einzige Ausgabe, bereit zum Senden, Speichern oder Zurückschreiben. `of_pretty` ist die eingerückte Form. `{}` wenn leer; der Aufruf leert nichts

Ein Dokument lesen #

Methode	Rolle
`of_load (string as_json)` → `long`	Lädt einen JSON-Text zum Lesen. Liefert `0`, wenn wohlgeformt, `-5`, wenn das Argument leer oder nur Leerraum ist (Leerzeichen, Tabulatoren, Zeilenumbrüche), `-4`, wenn es kein gültiges JSON ist oder mehr als 512 Ebenen verschachtelt (das Dokument wird dann verworfen). Parst in reinem PowerScript. Eine Bytereihenfolge-Markierung (U+FEFF) am Anfang, die einer als UTF-8 mit BOM gespeicherten Datei, wird übersprungen
`of_is_valid ( )` → `boolean`	Wahr, wenn das Objekt ein Dokument hält: das letzte `of_load` war erfolgreich, oder seitdem wurde etwas geschrieben. Ein an `of_set_raw` / `of_add_raw` übergebener Wert wird nicht erneut geprüft
`of_exists (string as_path)` → `boolean`	Wahr, wenn am angegebenen Pfad ein Wert liegt — unterscheidet einen vorhandenen, aber leeren Wert von einem fehlenden
`of_type (string as_path)` → `string`	Der JSON-Typ am Pfad: `object`, `array`, `string`, `number`, `boolean`, `null`; leer, wenn abwesend
`of_get_string (string as_path)` → `string`	Der Wert am Pfad, als Text: ein String kommt dekodiert zurück, eine Zahl/Boolean/null als Text, ein Objekt oder Array als rohes JSON (mit `of_load` neu ladbar); ein doppelt geschriebener Schlüssel wird bei seinem ERSTEN Vorkommen gelesen
`of_get_number (string as_path)` → `double`	Die Zahl am Pfad, als `double` — der Dezimalpunkt wird auf jeder Maschine beachtet (2.5 ist 2,5, nicht 2). `0`, wenn abwesend; der Exponent wird aufgelöst (`1e-7`, `2.5E+3`), 17 signifikante Stellen bleiben erhalten, führende Nullen des Exponenten eingeschlossen. Für einen Betrag oder eine ID, die alle Stellen behalten müssen: `of_get_decimal` oder `of_get_longlong`
`of_get_decimal (string as_path)` → `decimal`	Die Zahl am Pfad, als `decimal`, aus dem TEXT der Zahl neu aufgebaut und nie über ein `double`: `12345678901234.56` kommt mit seinen Cent zurück, `2.5E-3` ist `0.0025`. Höchstens 28 signifikante Stellen. `0`, wenn abwesend, wenn der Wert keine Zahl ist oder über das hinausgeht, was ein `decimal` fasst
`of_get_longlong (string as_path)` → `longlong`	Die Zahl am Pfad, als 64-Bit-Ganzzahl, aus ihrem Text neu aufgebaut und nie über ein `double`: eine Datenbank-ID wie `9007199254740993` kommt vollständig zurück. Nachkommastellen werden abgeschnitten (`2.9` ergibt `2`). `0`, wenn abwesend, wenn der Wert keine Zahl ist oder außerhalb des Bereichs eines `longlong` liegt
`of_get_boolean (string as_path)` → `boolean`	Der Boolean am Pfad: wahr nur für das JSON-Literal `true`
`of_count (string as_path)` → `long`	Die Anzahl der Mitglieder des Objekts oder Elemente des Arrays am Pfad. Liefert `-1`, wenn der Wert skalar oder abwesend ist (unterscheidet ein leeres Array, `0`, von einem fehlenden, `-1`). Mit `of_name` durchläuft man ein Objekt; ein Array wird über seinen Index im Pfad durchlaufen (`rows/1`, `rows/2`…)
`of_name (string as_path, long al_index)` → `string`	Der Name des `al_index`-ten Mitglieds (ab 1) des Objekts am Pfad — um die Schlüssel eines Objekts unbekannter Form zu lesen. Mit `of_count` durchläuft es das Objekt
`of_get_array (string as_path, ref string as_values[])` → `long`	Alle Elemente des Arrays am Pfad, der Reihe nach, in `as_values` (zuvor geleert) — jedes so, wie `of_get_string` es liest: ein String kommt dekodiert zurück, eine Zahl oder ein Boolean als Text, `null` als `""`, ein Objekt oder Array als rohes JSON (mit `of_load` in einem anderen `n_pbt_json` zu laden). `""` ist die Wurzel. Liefert die Anzahl der Elemente (`0` für ein leeres Array), `-4`, wenn am Pfad kein Array liegt (nichts, ein Objekt, ein Skalar), `-5` bei einem leeren Segment (`a//b`)
`of_pretty ( )` → `string`	Das Dokument — geladen oder gebaut — zum Lesen neu eingerückt (mehrere Zeilen, Tabulatoren) — ein Log, ein Textfeld. Leer, wenn keines da ist
`of_pretty (long al_indent)` → `string`	Das Dokument — geladen oder gebaut — mit `al_indent` Leerzeichen pro Ebene neu eingerückt (2 und 4 sind die üblichen Breiten). `0` schreibt es kompakt, auf einer Zeile und ohne Leerzeichen: der kleinste Text zum Speichern oder Senden. Leer, wenn kein Dokument da ist oder wenn `al_indent` negativ, größer als 16 oder null ist. `of_pretty()` ohne Argument behält die Tabulatoren

// Local variables
n_pbt_json  lnv_json
string      ls_tags[]
string      ls_compact
long        ll_count

// Read every element of an array at once, then store the document on one line
lnv_json.of_load(/*json*/ '{"customer":{"name":"Ada","tags":["vip","b2b"]}}')
ll_count = lnv_json.of_get_array(/*path*/ "customer/tags", /*values*/ ls_tags)   // 2 : vip, b2b

// The document on one line, without a space : the smallest text to store
ls_compact = lnv_json.of_pretty(/*indent*/ 0)

Ein Dokument ändern #

Die Schreib-Seite ändert das geladene Dokument an Ort und Stelle, dann liefert of_text das Ergebnis (kompakt) — das, was zurückgeschrieben wird. Die Setter ersetzen den Wert am Pfad oder fügen den letzten Schlüssel hinzu, wenn er einem Elternobjekt fehlt. Jeder liefert 0, -4 wenn der Elternteil fehlt oder vom falschen Typ ist, -5 bei leerem Pfad oder einem Index 0 auf einem Array. Ein Array auf dem Weg wird über einen VORHANDENEN Index durchquert (items/1/qty fügt qty dem ersten Element hinzu); angelegt wird immer nur ein Objektschlüssel. Ein null-Wert (Zahl, Boolean, leeres rohes JSON) wird als null geschrieben.

Element	Rolle
`of_set_string (string as_path, string as_value)` → `long`	SCHREIBT eine Zeichenkette unter `as_path`, für Sie maskiert. Der Pfad darf MEHRERE Ebenen haben (`a/b/c`): fehlende werden als OBJEKTE angelegt, und ein LEERES Dokument wird zu einem — Schreiben IST Bauen. Ein bereits vorhandener Wert wird ersetzt, wo immer er steht. Liefert `0`, `-4`, wenn eine Ebene unterwegs ein Skalar ist oder ein Array ohne diesen Index (ein Array wird über einen vorhandenen Index durchquert: `items/1/qty`), `-5` bei leerem Pfad, leerem Segment oder einem Index 0 auf einem Array. Eine Null-Zeichenkette wird leer geschrieben; für ein JSON-`null`: `of_set_raw(as_path, "null")`
`of_set_number (string as_path, long al_value)` → `long`	SCHREIBT eine ZAHL unter `as_path`, der Dezimalpunkt erzwungen. Fünf Überladungen: `integer`, `long`, `longlong`, `decimal`, `double` — ein `decimal` und ein `longlong` behalten ALLE Stellen (die Cent eines Betrags, die letzte Stelle einer ID über 2^53), und ein Literal wie `690.50` ist ein `decimal`, geschrieben `690.5`. Gleiche Pfadregel und gleiche Codes wie `of_set_string`; ein Null-Wert schreibt `null`
`of_set_boolean (string as_path, boolean ab_value)` → `long`	SCHREIBT einen BOOLESCHEN Wert unter `as_path`: `true` oder `false`, nie in Anführungszeichen. Gleiche Pfadregel und gleiche Codes wie `of_set_string`; ein Null-Wert schreibt `null`
`of_set_raw (string as_path, string as_json)` → `long`	SCHREIBT unter `as_path` einen Wert, der BEREITS JSON ist — ein verschachteltes Objekt, ein Array, `null` — so wie er ist: Sie stehen dafür ein. So wird auch ein Array vor `of_add_*` GEÖFFNET. Gleiche Pfadregel und gleiche Codes wie `of_set_string`; ein leerer oder Null-Wert schreibt `null`
`of_remove (string as_path)` → `long`	Entfernt den Wert am Pfad — ein Objektmitglied (sein Schlüssel und ein Komma gehen mit) oder ein Array-Element; das Ergebnis bleibt gültig. Liefert `0`, `-4`, wenn dort nichts ist, `-5` bei leerem Pfad, leerem Segment oder einem Index 0 auf einem Array

// Local variables
n_pbt_json  lnv_json

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

// lnv_json.of_text() -> {"name":"Grace","active":true,"count":3}

Umfang. JSON parst in reinem PowerScript, ohne Seite oder Engine: n_pbt_json bleibt autoinstantiate und funktioniert überall, PowerBuilder 10 inbegriffen. Für XML siehe xml (das auf die Engine baut); um ein JSON als aufklappbaren Baum zu zeigen, siehe jsontree.