# HG changeset patch
# User Mahlon Smith <mahlon@martini.nu>
# Date 1432081636 0
# Node ID ef9f89362aac79cd820986d153c8ef1beb1960bf
# Parent  05f836c0215436230d703233bea133c5d16ebc3f
README.md edited online with Bitbucket

diff -r 05f836c02154 -r ef9f89362aac README.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.md	Wed May 20 00:27:16 2015 +0000
@@ -0,0 +1,80 @@
+# README #
+
+### What's this? ###
+
+This module implements a simple TNetstring parser and serializer.
+TNetString stands for "tagged netstring" and is a modification of Dan
+Bernstein's netstrings specification.  TNetstrings allow for the same
+data structures as JSON but in a format that is resistant to buffer
+overflows and backward compatible with original netstrings.  They make
+no assumptions about string contents, allowing for easy transmission of
+ascii and binary data mixed with strongly typed values.
+
+See http://cr.yp.to/proto/netstrings.txt and http://tnetstrings.org/ for
+additional information.
+
+
+### Installation ###
+
+The easiest way to install this module is via the nimble package manager, 
+by simply running 'nimble install tnetstring'.
+
+Alternatively, you can fetch the 'tnetstring.nim' file yourself, and put it in a place of your choosing.
+
+### Usage ###
+
+```
+#!nimrod
+import tnetstring
+
+  let
+      tnetstr = "52:4:test,3:1.3^4:key2,4:true!6:things,12:1:1#1:2#1:3#]}"
+      tnetobj = parse_tnetstring( tnetstr )
+
+  # tnetobj is now equivalent to the structure:
+  # @[(key: test, val: 1.3), (key: key2, val: true), (key: things, val: @[1, 2, 3])]
+
+  assert( tnetobj.kind == TNetstringObject )
+  echo tnetobj[ "test" ]
+  echo tnetobj[ "key2" ]
+  for item in tnetobj[ "things" ]:
+      echo item
+```
+
+Results in:
+
+```
+#!nimrod
+  1.3
+  true
+  1
+  2
+  3
+```
+
+This module can also be used to reasonably create a serialized
+TNetstring, suitable for network transmission:
+
+```
+#!nimrod
+   let
+       number  = 1000
+       list    = @[ "thing1", "thing2" ]
+       tnettop = newTNetstringArray() # top-level array
+       tnetsub = newTNetstringArray() # sub array
+   
+   tnettop.add( newTNetstringInt(number) )
+   for item in list:
+       tnetsub.add( newTNetstringString(item) )
+   tnettop.add( tnetsub )
+   
+   # Equivalent to: @[1000, @[thing1, thing2]]
+   echo dump_tnetstring( tnettop )
+```
+
+Results in:
+
+```
+#!nimrod
+   29:4:1000#18:6:thing1,6:thing2,]]
+```
\ No newline at end of file