json(3tcl)

NAME
json - JSON parser

SYNOPSIS
package require Tcl 8.4

package require json ?1.3.3?

::json::json2dict txt

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

DESCRIPTION

The json package provides a simple Tcl-only library for parsing the JSON http://www.json.org/ data exchange format as specified in RFC 4627 http://www.ietf.org/rfc/rfc4627.txt. There is some ambiguity in parsing JSON because JSON has type information that is not maintained by the Tcl conversion. The json package returns data as a Tcl dict. Either the dict package or Tcl 8.5 is required for use.

COMMANDS

::json::json2dict txt
    Parse JSON formatted text txt into a Tcl dict and return the value.

    If txt contains more than one JSON entity only the first one is returned.

::json::many-json2dict txt ?max?
    Parse JSON formatted text txt containing multiple JSON entities into a list of dictionaries and return that list.

    If max is specified exactly that many entities are extracted from txt. By default the command will attempt to extract all, without limits. A value of "max == 0" does not make sense and will cause the command to throw an error.

EXAMPLES

An example of a JSON array converted to Tcl. A JSON array is returned 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}

An example of a JSON object converted to Tcl. A JSON object is returned as a multi-element list (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}}

BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category json of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.

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