1[comment {-*- tcl -*- doctools manpage}]
2[manpage_begin json n 1.1]
3[copyright {2006 ActiveState Software Inc., 2009 Thomas Maeder, Glue Software Engineering AG}]
4[moddesc   {JSON}]
5[titledesc {JSON parser}]
6[category  {CGI programming}]
7[require Tcl 8.4]
8[require json [opt 1.1]]
9[keywords json javascript {data exchange} {exchange format}]
10[description]
11[para]
12
13The [package json] package provides a simple Tcl-only library for parsing the
14JSON [uri http://www.json.org/] data exchange format as specified in RFC 4627
15[uri http://www.ietf.org/rfc/rfc4627.txt].
16
17There is some ambiguity in parsing JSON because JSON has type information that
18is not maintained by the Tcl conversion.  The [package json] package returns
19data as a Tcl [cmd dict].  Either the [package dict] package or Tcl 8.5 is
20required for use.
21
22[section COMMANDS]
23
24[list_begin definitions]
25
26[call [cmd ::json::json2dict] [arg txt]]
27
28Parse JSON formatted text [arg txt] into a Tcl dict and return the value.
29
30[list_end]
31[para]
32
33[section EXAMPLES]
34[para]
35
36An example of a JSON array converted to Tcl.  A JSON array is returned as a
37single item with multiple elements.
38
39[para]
40[example {[
41    {
42       "precision": "zip",
43       "Latitude":  37.7668,
44       "Longitude": -122.3959,
45       "Address":   "",
46       "City":      "SAN FRANCISCO",
47       "State":     "CA",
48       "Zip":       "94107",
49       "Country":   "US"
50    },
51    {
52       "precision": "zip",
53       "Latitude":  37.371991,
54       "Longitude": -122.026020,
55       "Address":   "",
56       "City":      "SUNNYVALE",
57       "State":     "CA",
58       "Zip":       "94085",
59       "Country":   "US"
60    }
61]
62=>
63{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}
64}]
65[para]
66
67An example of a JSON object converted to Tcl.  A JSON object is returned as a
68multi-element list (a dict).
69
70[para]
71[example {{
72    "Image": {
73        "Width":  800,
74        "Height": 600,
75        "Title":  "View from 15th Floor",
76        "Thumbnail": {
77            "Url":    "http://www.example.com/image/481989943",
78            "Height": 125,
79            "Width":  "100"
80        },
81        "IDs": [116, 943, 234, 38793]
82    }
83}
84=>
85Image {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}}
86}]
87
88[vset CATEGORY json]
89[include ../doctools2base/include/feedback.inc]
90[manpage_end]
91