xcall JSON, opcode, {, parameters...}
JSON performs various JSON-related utility functions.
Parameters
opcode [in]
specifies operation to be performed, described in detail below.
u Opcode 1: Load a JSON string into an ordered map
xcall JSON, 1, handle, status, jsontext$, $ordmap() Parameters handle (B4+ or F) [out] returns a handle to the JSON structure in memory (for future expansion) status (Signed Num) [out] returns the status of the operation:
The resulting map uses an XPATH-like syntax, consisting of a key representing the path to the value and the value representing the value. For example, the following JSON excerpt describing a program menu bar ... { "menu": { "header": "SVG Viewer", "items": [ {"id": "Open"}, {"id": "OpenNew", "label": "Open New"}, null, {"id": "ZoomIn", "label": "Zoom In"}, ...
... would be converted to an ordered map something like this: /menu/header -> SVG Viewer /menu/items[1]/id -> Open /menu/items[2]/id -> OpenNew /menu/items[2]/label -> Open New /menu/items[4]/id -> ZoomIn /menu/items[4]/label -> Zoom In ...
Note that you can use the function Fn'FileToStr$(fspec$) from fnfilestr.bsi in SOSLIB[907,10] to load a JSON file into the string needed by the JSON function. |
u Opcode 2: Free the JSON memory associated with the HANDLE
xcall JSON, 2, handle, status Parameters handle (B4+ or F) [in] handle returned from opcode 1 status (Signed Num) [out] - 0 for success |
u Opcode 3: Escape the JSON text
xcall JSON, 3, status, jsontext$ Parameters status (Signed Num) [out] returns the number of special characters escaped jsontext$ (String) [in/out] JSON text, both source and destination This function applies JSON escaping rules to special characters in the specified JSONTEXT$, returning the resulting string in the same variable. Note that since escaping increases the size of the text, the JSONTEXT$ parameter should be sufficiently large to handle the worst case, which could be up to six times the original, or be a dynamic string. The algorithm assumes that the JSONTEXT$ is encoded using the Latin1 character set, and supports the following:
Note that aside from eliminating the need to reinvent the wheel in a BASIC function, the subroutine operates much faster than you could possibly do in BASIC. |
u Opcode 4: Unescape the JSON text
xcall JSON, 4, status, jsontext$ Parameters status (Signed Num) [out] returns the number of escaped characters unescaped jsontext$ (String) [in/out] JSON text, both source and destination This is the reverse of opcode 3, converting the escaped sequences into their original raw form. Note that here the output will never be longer than the input. |
u Opcode 5: Form a "name":"value" pair
xcall JSON, 5, status, name$, value$, jsonpair$ {,flags} Parameters status not used name$ (String) [in] the name part of the name:value pair value$ (String) [in] the value part of the name:value pair jsontext$ (String) [out] the "name":"value" result is returned here flags (Num) [in] optional flags from the table below
Although this may seem like a minimal operation that can easily be accomplished in a simple BASIC function, as with opcode 3 and 4, the big advantage is speed, which might matter when dealing with large datasets involving hundreds of thousands or millions of such pairs. Note that unless the XJSONF_NOCOMMA flag is specified, the output will contain a trailing comma so that you can call the function in a loop without having to explicitly output a comma between each pair. |
||||||||||||||||||||||||
History
2021 October, A-Shell 6.5.1708: Routine added to A-Shell
