summaryrefslogtreecommitdiffstats
path: root/tcllib/modules/json/json.man
diff options
context:
space:
mode:
authorWilliam Joye <wjoye@cfa.harvard.edu>2016-10-27 19:39:39 (GMT)
committerWilliam Joye <wjoye@cfa.harvard.edu>2016-10-27 19:39:39 (GMT)
commitea28451286d3ea4a772fa174483f9a7a66bb1ab3 (patch)
tree6ee9d8a7848333a7ceeee3b13d492e40225f8b86 /tcllib/modules/json/json.man
parentb5ca09bae0d6a1edce939eea03594dd56383f2c8 (diff)
parent7c621da28f07e449ad90c387344f07a453927569 (diff)
downloadblt-ea28451286d3ea4a772fa174483f9a7a66bb1ab3.zip
blt-ea28451286d3ea4a772fa174483f9a7a66bb1ab3.tar.gz
blt-ea28451286d3ea4a772fa174483f9a7a66bb1ab3.tar.bz2
Merge commit '7c621da28f07e449ad90c387344f07a453927569' as 'tcllib'
Diffstat (limited to 'tcllib/modules/json/json.man')
-rw-r--r--tcllib/modules/json/json.man110
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]