@JsonParse

Diese @Function analysiert eine JSON-Textdarstellung und erzeugt daraus eine JSON-Struktur.

Als Eingabe kann entweder ein TEXT oder ein VSPECBINBUFFER übergeben werden. Der Inhalt wird als JSON interpretiert und muss in UTF-8 vorliegen.

Bei erfolgreicher Verarbeitung liefert @JsonParse ein VSPECHJSON (HJS) Handle auf die erzeugte JSON-Struktur zurück.
Das Handle kann anschließend beispielsweise mit @JsonGet, @JsonAdd oder @JsonSerialize verwendet werden und muss nach seiner Verwendung mit @JsonRelease wieder freigegeben werden.

Standardmäßig werden die normalen Regeln des JSON-Parsers verwendet.
Über den optionalen numerischen Parameter FN OPTIONS können zusätzliche Parser-Optionen angegeben werden. Der Wert wird direkt als Options- beziehungsweise Flag-Wert an den JSON-Parser übergeben.

Kann die Eingabe nicht als gültiges JSON interpretiert werden, liefert @JsonParse @ERROR.
Die Fehlermeldung enthält dabei die Position des Fehlers innerhalb der JSON-Daten sowie einen Fehlercode und eine Beschreibung des Parser-Fehlers.

TEXT/VSPECBINBUFFER INPUT:
JSON-Daten, die analysiert werden sollen.
Die JSON-Daten müssen in UTF-8 vorliegen.

Beispiel mit TEXT:
HJSON:=@JsonParse("{\"Name\":\"Max Mustermann\",\"Age\":42}");

Die erzeugte JSON-Struktur entspricht:
{
"Name":"Max Mustermann",
"Age":42
}

Das zurückgegebene Handle kann anschließend verwendet werden:
NAME:=@JsonGet(HJSON;"Name");
AGE:=@JsonGet(HJSON;"Age");
@JsonRelease(HJSON);

FN OPTIONS:
Optionaler numerischer Options- beziehungsweise Flag-Wert für den JSON-Parser.
Wird OPTIONS nicht angegeben, wird der Wert 0 verwendet und das JSON mit den Standardoptionen des Parsers verarbeitet.
Die angegebenen Flags werden unverändert an den zugrunde liegenden JSON-Parser weitergegeben und können, soweit vom Parser unterstützt, miteinander kombiniert werden.

BIT   DEC   HEX   BEDEUTUNG wenn gesetzt
01   000001   00001   JSON_REJECT_DUPLICATES
02   000002   00002   JSON_DISABLE_EOF_CHECK
03   000004   00004   JSON_DECODE_ANY
04   000008   00008   JSON_DECODE_INT_AS_REAL
05   000016   00010   JSON_ALLOW_NUL

Für die normale Verarbeitung eines JSON-Objects oder JSON-Arrays ist die Angabe von OPTIONS normalerweise nicht erforderlich.

JSON-Object:
Ein JSON-Object kann direkt aus einem TEXT erzeugt werden:

JSONTEXT:="{\"Name\":\"Max Mustermann\",\"Active\":true,\"Value\":12.5}";
HJSON:=@JsonParse(JSONTEXT);
NAME:=@JsonGet(HJSON;"Name");
ACTIVE:=@JsonGet(HJSON;"Active");
VALUE:=@JsonGet(HJSON;"Value");
@JsonRelease(HJSON);

Die JSON-Struktur entspricht:
{
"Name":"Max Mustermann",
"Active":true,
"Value":12.5
}

JSON-Array:
Auch ein JSON-Array kann direkt verarbeitet werden:

HJSON:=@JsonParse("[\"A\",\"B\",\"C\"]");
VALUE1:=@JsonGet(HJSON;0);
VALUE2:=@JsonGet(HJSON;1);
VALUE3:=@JsonGet(HJSON;2);
@JsonRelease(HJSON);

Die erzeugte JSON-Struktur entspricht:
["A","B","C"]

Da JSON-Arrays 0-basiert indiziert werden, enthält VALUE1 den Wert "A", VALUE2 den Wert "B" und VALUE3 den Wert "C".

VSPECBINBUFFER als INPUT:
JSON-Daten können auch aus einem VSPECBINBUFFER gelesen werden.

In diesem Fall werden exakt die durch USEDSIZE (siehe @GetBufferInfo) angegebenen Bytes des Buffers an den JSON-Parser übergeben.
Dies eignet sich insbesondere für JSON-Daten, die beispielsweise über HTTP oder REST empfangen wurden.
Der Inhalt des Buffers muss gültiges UTF-8-JSON enthalten.
Ein eventuell vorhandenes abschließendes NULL-Byte (0x00) darf dabei nicht Bestandteil von USEDSIZE sein, da bei einem VSPECBINBUFFER alle durch USEDSIZE angegebenen Bytes als Bestandteil der JSON-Eingabe interpretiert werden.

Enthält ein Buffer beispielsweise:
7B 22 41 22 3A 31 7D 00
entspricht dies:
{"A":1}\0

Für die Verarbeitung muss USEDSIZE in diesem Fall nur die Bytes von:
{"A":1}
umfassen. Ein zusätzlich übergebenes 0x00 kann zu einem Parser-Fehler führen.

Fehlerbehandlung:
Kann die Eingabe nicht als gültiges JSON interpretiert werden, liefert @JsonParse @ERROR.

Die Fehlermeldung besitzt das Format:
INVALID JSON AT LINE <line>, COLUMN <column>, POSITION <position>: ErrorCode:<code> <description>

Beispielsweise kann eine fehlerhafte Eingabe wie:
{"Name":"Max Mustermann","Age":42
zu einer Fehlermeldung in der folgenden Form führen:
INVALID JSON AT LINE 1, COLUMN …, POSITION …: ErrorCode:… …

Dabei bedeuten:
LINE Zeile, in der der Fehler erkannt wurde
COLUMN Spalte innerhalb der Zeile
POSITION Position innerhalb der Eingabedaten
ErrorCode numerischer Fehlercode des JSON-Parsers
description Beschreibung des Parser-Fehlers

Dadurch können Syntaxfehler, ungültige UTF-8-Daten oder unvollständige JSON-Strukturen genauer lokalisiert werden.

Hinweise:
@JsonParse führt keine Zeichensatzkonvertierung durch. Die Eingabedaten müssen bereits als gültiges UTF-8 vorliegen.
Insbesondere dürfen Daten aus TEXT-Feldern, die ursprünglich in LMBCS vorliegen, nicht ohne vorherige Konvertierung als UTF-8-JSON behandelt werden.
Das von @JsonParse zurückgegebene VSPECHJSON (HJS) Handle besitzt eine eigene Referenz auf die erzeugte JSON-Struktur und muss nach der Verwendung mit @JsonRelease wieder freigegeben werden.

Beispiel: @JsonParse(INPUT);

JSONTEXT:="{\"Name\":\"Max Mustermann\",\"Age\":42,\"Active\":true,\"Values\":[10,20,30]}";
HJSON:=@JsonParse(JSONTEXT);
NAME:=@JsonGet(HJSON;"Name");
AGE:=@JsonGet(HJSON;"Age");
ACTIVE:=@JsonGet(HJSON;"Active");
VALUES:=@JsonGet(HJSON;"Values";"L");
@JsonRelease(HJSON);

Die erzeugte JSON-Struktur entspricht:
{
"Name":"Max Mustermann",
"Age":42,
"Active":true,
"Values":[10,20,30]
}

Die Return-Werte entsprechen:
NAME "Max Mustermann"
AGE 42
ACTIVE 1
VALUES 10, 20, 30

VALUES wird dabei durch die Option "L" von @JsonGet als FLOATLIST zurückgegeben.