json(3tcl)

💖 json — the JSON parser page, but make it cute 💖

okay bestie, so this is the json(3tcl) manual page — like, the JSON section of the Tcllib docs, and we're about to read it together. grab a boba, it's gonna be fun. 🧋✨

---

🎀 NAME 🎀

json — JSON parser. that's it. that's the name. short, sweet, iconic. 👑

---

✨ SYNOPSIS ✨

like, the whole vibe in one glance:

package require Tcl 8.5 9

package require json ?1.3.6?

::json::json2dict txt

::json::many-json2dict txt ?max?

---

🌸 DESCRIPTION 🌸

so the json package is a simple, Tcl-only library for parsing the JSON data exchange format — you know, the one at http://www.json.org/ — exactly as specified in RFC 4627 (http://www.ietf.org/rfc/rfc4627.txt). no C extensions, no drama, just Tcl doing its thing. 💅

now here's the tea: there's some ambiguity in parsing JSON, because JSON carries type information that Tcl's conversion just… doesn't keep. it's giving "we don't do types here." 🫠 so the json package hands you back your data as a Tcl dict. and because of that, you need either the dict package or Tcl 8.5 to use it. no cap.

---

🦋 COMMANDS 🦋

::json::json2dict txt

parses JSON-formatted text txt into a Tcl dict and returns that value. simple. clean. ate. ✨

• if txt contains more than one JSON entity, only the first one gets returned. that's it, bestie, the rest just sits there unread. 🙈

::json::many-json2dict txt ?max?

parses JSON-formatted text txt that contains multiple JSON entities and returns them as a list of dictionaries. the more the merrier. 🔥

• if max is specified, exactly that many entities get extracted from txt.
• by default, the command will try to extract all of them — no limits, main character energy. 👑
• a value of "max == 0" does not make sense and will cause the command to throw an error. so like… don't. 💀

---

🌈 EXAMPLES 🌈

an example of a JSON array converted to Tcl 📦

a JSON array comes back as a single item with multiple elements. watch:

[
    {
       "precision": "zip",
       "Latitude":  37.7668,
       "Longitude": -122.3959,
       "Address":   "",
       "City":      "SAN FRANCISCO",
       "State":     "CA",
       "Zip":       "94107",
       "Country":   "US"
    },
    {
       "precision": "zip",
       "Latitude":  37.371991,
       "Longitude": -122.026020,
       "Address":   "",
       "City":      "SUNNYVALE",
       "State":     "CA",
       "Zip":       "94085",
       "Country":   "US"
    }
]
=>
{Country US Latitude 37.7668 precision zip State CA City {SAN FRANCISCO} Address {} Zip 94107 Longitude -122.3959} {Country US Latitude 37.371991 precision zip State CA City SUNNYVALE Address {} Zip 94085 Longitude -122.026020}

an example of a JSON object converted to Tcl 🎁

a JSON object comes back as a multi-element list (a dict). periodt.

{
    "Image": {
        "Width":  800,
        "Height": 600,
        "Title":  "View from 15th Floor",
        "Thumbnail": {
            "Url":    "http://www.example.com/image/481989943",
            "Height": 125,
            "Width":  "100"
        },
        "IDs": [116, 943, 234, 38793]
    }
}
=>
Image {IDs {116 943 234 38793} Thumbnail {Width 100 Height 125 Url http://www.example.com/image/481989943} Width 800 Height 600 Title {View from 15th Floor}}

---

💜 RELATED 💜

if you wanna write JSON instead of parsing it, go look at the json::write package. different girl, different job. 💅

---

😭 BUGS, IDEAS, FEEDBACK 😭

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. it's giving humble. please report them in the category json of the Tcllib Trackers here: http://core.tcl.tk/tcllib/reportlist. and if you have ideas for enhancements for the package and/or the documentation, send those too. we're listening. 🫶

when you propose code changes, please provide unified diffs — i.e. the output of diff -u. that's the standard, bestie.

also important: attachments are strongly preferred over inlined patches. you make an attachment by going to the Edit form of the ticket immediately after creating it, and then using the left-most button in the secondary navigation bar. yep, that specific one. 🎯

---

⭐ KEYWORDS ⭐

data exchange, exchange format, javascript, json

---

🌸 CATEGORY 🌸

CGI programming

---

👑 COPYRIGHT 👑

Copyright (c) 2006 ActiveState Software Inc.
Copyright (c) 2009 Thomas Maeder, Glue Software Engineering AG

---

okay that's the whole page!! this was tcllib version 1.3.6, the json(3tcl) page, and that's the vibe check complete. go parse something gorgeous, bestie. 💖✨🦋🎀