Merge commit '7c621da28f07e449ad90c387344f07a453927569' as 'tcllib'

1 files changed, 110 insertions, 0 deletions

diff --git a/tcllib/modules/json/json.man b/tcllib/modules/json/json.man
new file mode 100644
index 0000000..1e9088c
--- /dev/null
+++ b/tcllib/modules/json/json.man
@@ -0,0 +1,110 @@
+[comment {-*- tcl -*- doctools manpage}]
+[vset VERSION 1.3.3]
+[manpage_begin json n [vset VERSION]]
+[keywords {data exchange}]
+[keywords {exchange format}]
+[keywords javascript]
+[keywords json]
+[copyright {2006 ActiveState Software Inc.}]
+[copyright {2009 Thomas Maeder, Glue Software Engineering AG}]
+[moddesc   {JSON}]
+[titledesc {JSON parser}]
+[category  {CGI programming}]
+[require Tcl 8.4]
+[require json [opt [vset VERSION]]]
+[description]
+[para]
+
+The [package json] package provides a simple Tcl-only library for parsing the
+JSON [uri http://www.json.org/] data exchange format as specified in RFC 4627
+[uri 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 [package json] package returns
+data as a Tcl [cmd dict].  Either the [package dict] package or Tcl 8.5 is
+required for use.
+
+[section COMMANDS]
+
+[list_begin definitions]
+
+[call [cmd ::json::json2dict] [arg txt]]
+
+Parse JSON formatted text [arg txt] into a Tcl dict and return
+the value.
+
+[para] If [arg txt] contains more than one JSON entity only the
+first one is returned.
+
+
+[call [cmd ::json::many-json2dict] [arg txt] [opt [arg max]]]
+
+Parse JSON formatted text [arg txt] containing multiple JSON entities
+into a list of dictionaries and return that list.
+
+[para] If [arg max] is specified exactly that many entities are extracted
+from [arg txt]. By default the command will attempt to extract all, without
+limits. A value of "[arg max] == 0" does not make sense and will cause the
+command to throw an error.
+
+[list_end]
+[para]
+
+[section EXAMPLES]
+[para]
+
+An example of a JSON array converted to Tcl.  A JSON array is returned as a
+single item with multiple elements.
+
+[para]
+[example {[
+    {
+       "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}
+}]
+[para]
+
+An example of a JSON object converted to Tcl.  A JSON object is returned as a
+multi-element list (a dict).
+
+[para]
+[example {{
+    "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}}
+}]
+
+[vset CATEGORY json]
+[include ../doctools2base/include/feedback.inc]
+[manpage_end]