README.md edited online with Bitbucket

FossilOrigin-Name: eeaafe9863183543e61da62c7beec7c1778a61f233f2b10c5ada0f87009a6ccb

README.md

@@ -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,]]
+```