json/json.man

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