NAME

       json - JSON parser

SYNOPSIS

       package require Tcl  8.4

       package require json  ?1.3.4?

       ::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}}

RELATED

       To write json, instead of parsing it, see package json::write.

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.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made 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.

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