GOLF(2gg)

NAME
json-doc - (JSON-parsing)

PURPOSE
Parse JSON text.

SYNTAX

        json-doc <text> to <json> \
            [ status <status> ] [ length <length> ] [ noencode ] [ no-enum ] \
            [ error-text <error text> ] \
                [ error-position <error position> ] \
                [ error-line <line> ] \
                [ error-char <char> ]

        json-doc  delete <json>

DESCRIPTION
json-doc will parse JSON <text> into <json> variable, which can be used with read-json to get the data.

The length of <text> may be specified with "length" clause in <length> variable, or if not, it will be the string length of <text>.

The "status" clause specifies the return <status> number, which is GG_OKAY if successful or GG_ERR_JSON if there is an error. The number <error position> in "error-position" clause is the byte position in <text> where error was found (starting with "0"), in which case <error text> in "error-text" clause is the error message. You can also obtain the error's line number (with number <line> in clause "error-line") and the character position within that line (with number <char> in clause "error-char").

"noencode" clause will not encode strings, i.e. convert from JSON Unicode strings to UTF, nor will it perform any validity checks on strings. This may be useful as a performance boost or to pass along strings unencoded, however in most cases it is not needed.

"no-enum" clause will not include indexing of arrays in normalized names (with "[..]"), see read-json. This is useful if you want to check the path of each data element, and not worry about counting them; this happens often when using JSON in a structured way to transfer arrays when data elements repeat in a predictable fashion. Parsing of JSON is also faster with "no-enum".

The maximum depth of nested structures in JSON document (i.e. objects and arrays) is 32, and the maximum length of normalized leaf node name is 1024 (see read-json for more on normalized names). There is no limit on document size.

DELETING

To delete a JSON variable, use "delete" clause with the <json>. This will delete all memory associated with it, and the variable <json> itself.

EXAMPLES
Parse the following JSON document and display all keys and values from it. You can use them as they come along, or store them into new-hash or new-tree for instance for searching of large documents. This also demonstrates usage of UTF8 characters:

        // JSON to parse
        set-string jd unquoted = {"menu":\
            {"id": "file",\
            "value": 23091,\
            "active": false,\
            "popup":\
                {"menuitem":\
                    [{"value": "New", "onclick": "CreateNewDoc with\uD834\uDD1Emusic"},\
                    {"value": "Open", "onclick": "OpenDoc() with \uD834\uDD1E\uD834\uDD1E"},\
                    {"value": "Close", "onclick": "\uD834\uDD1ECloseDoc()"}\
                    ]\
                }\
            }\
        }

        // Parse JSON
        json-doc jd status st error-text et error-position ep to nj

        // Check parsing okay, if not display error details
        if-true st not-equal GG_OKAY
            @Error [<<print-out et>>] at [<<print-out ep>>]
            exit-handler -1
        end-if

        // Display all data elements in order from top to bottom
        start-loop
            read-json nj key k value v type t next
            if-true t equal GG_JSON_TYPE_NONE
                break-loop
            end-if
            @Key [<<print-out k>>]
            @Value [<<print-out v>>]
            @Type [<<print-out t>>]
            @--------
        end-loop
        @

        // Delete JSON document
        json-doc delete nj

The output would be:

        Key ["menu"."id"]
        Value [file]
        Type [0]
        --------
        Key ["menu"."value"]
        Value [23091]
        Type [1]
        --------
        Key ["menu"."active"]
        Value [false]
        Type [3]
        --------
        Key ["menu"."popup"."menuitem"[0]."value"]
        Value [New]
        Type [0]
        --------
        Key ["menu"."popup"."menuitem"[0]."onclick"]
        Value [CreateNewDoc with𝄞music]
        Type [0]
        --------
        Key ["menu"."popup"."menuitem"[1]."value"]
        Value [Open]
        Type [0]
        --------
        Key ["menu"."popup"."menuitem"[1]."onclick"]
        Value [OpenDoc() with 𝄞𝄞]
        Type [0]
        --------
        Key ["menu"."popup"."menuitem"[2]."value"]
        Value [Close]
        Type [0]
        --------
        Key ["menu"."popup"."menuitem"[2]."onclick"]
        Value [𝄞CloseDoc()]
        Type [0]
        --------

Note that if "no-enum" were used in json-doc, then all keys with arrays would not have "[..]", for instance the very last key above would be "menu"."popup"."menuitem"."onclick", i.e. there would be no indexing of arrays.

SEE ALSO
 JSON parsing

json-doc read-json See all documentation