GOLF(2gg)

💖 GOLF(2gg) — the json-doc page, bestie edition 💖

okay so we're in the Development manual section of GOLF(2gg), and today's main character is json-doc. sit down, grab a strawberry 🍓, we're parsing JSON.

---

✨ NAME ✨

json-doc — the JSON-parsing one 🦋

---

🎀 PURPOSE 🎀

Parse JSON text. that's it, that's the job. slay 💅

---

🌸 SYNTAX 🌸

    [ 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 the <json> variable, and then you can use read-json to actually get the data out of it. yes bestie, that's the whole flow 🫶

The length of <text> may be specified with the "length" clause in the <length> variable, or, if you don't bother, it just defaults to the string length of <text>. lowkey convenient.

The "status" clause specifies the return <status> number, which is GG_OKAY if everything went iconic, or GG_ERR_JSON if there was an error. and when there IS an error: the number <error position> in the "error-position" clause is the byte position in <text> where the error was found (and it starts with "0", no cap), and in that case <error text> in the "error-text" clause is the error message. you can also get the error's line number (that's number <line> in the "error-line" clause) and the character position within that line (number <char> in the "error-char" clause). full detective mode 🔍

"noencode" clause will not encode strings, i.e. it won't convert from JSON Unicode strings to UTF, and it also won't perform any validity checks on strings. this may be useful as a performance boost, or to pass strings along unencoded — but in most cases it is not needed. fr fr, don't reach for it unless you know why.

"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 — which happens often when you're using JSON in a structured way to transfer arrays where data elements repeat in a predictable fashion. also, parsing of JSON is faster with "no-enum". so it's giving both vibes and speed ✨

🚨 heads up on the limits: the maximum depth of nested structures in a JSON document (i.e. objects and arrays) is 32, and the maximum length of a normalized leaf node name is 1024 (see read-json for more on normalized names). There is no limit on document size though. go feral, write a giant file 📄

🫶 DELETING

To delete a JSON variable, use the "delete" clause with the <json>. This will delete all memory associated with it, and the variable <json> itself. it's gone, it's deleted, periodt 💀

---

🌈 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. iykyk 💜

---

💜 SEE ALSO 💜

• JSON parsing
• json-doc
• read-json
• See all documentation

---

and that's the whole page bestie!! 🎀 this version was born on $DATE, running the $VERSION flavor, and it lives forever under the GOLF(2gg) banner. go parse something cute 💖✨🦋