json(n)

✨ json(n) ✨

okay bestie, gather round 💖 this is the manual page for json, the JSON parser in Tcl land. Yes it's a Tcl thing. Yes it's cute. Let's go 🦋

---

NAME

json — it's a JSON parser, that's the whole vibe 💅

---

SYNOPSIS

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 literally a simple Tcl-only library for parsing the JSON data exchange format — that's http://www.json.org/ — exactly as specified in RFC 4627 over at http://www.ietf.org/rfc/rfc4627.txt. no cap 🌸

and here's the tea: there is some ambiguity when parsing JSON, because JSON carries type information that Tcl's conversion just does not maintain. it's giving "we lost the receipts" 😭

the json package hands you back your data as a Tcl dict. and heads up — you need either the dict package or Tcl 8.5 for any of this to work. non-negotiable bestie 🫶

---

COMMANDS

• ::json::json2dict txt — parses JSON formatted text txt into a Tcl dict and returns that value. 💖

lowkey important: if txt contains more than one JSON entity, only the first one comes back. the rest just... don't get an invite 🙈

• ::json::many-json2dict txt ?max? — parses JSON formatted text txt that contains multiple JSON entities, into a list of dictionaries, and returns that list. iconic ✨

if max is specified, exactly that many entities are extracted from txt. by default the command tries 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. don't do it. fr fr 💀

---

EXAMPLES

first up: a JSON array converted to Tcl. a JSON array comes back as a single item with multiple elements 🌈

[
    {
       "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}

and now a JSON object converted to Tcl. a JSON object comes back as a multi-element list — which is, you guessed it, a dict 🎀

{
    "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

wanna write json instead of parsing it? different girl, different page — go see package json::write. 💜

---

BUGS, IDEAS, FEEDBACK

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. it's giving "we're all just doing our best" 😭

please report them in the category json of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist

also pls pls pls report any ideas you have for enhancements to either the package and/or the documentation. we love ideas here 🫶✨

if you're proposing code changes, send unified diffs — that's the output of diff -u. periodt.

💅 one more thing: attachments are strongly preferred over inlined patches. you make an attachment by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. iykyk.

---

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

---

and that's the whole page bestie 💖 this one ships with tcllib, version 1.3.6, and it's filed under the manual name json(n). slay, go parse something gorgeous ✨👑💅