1 # README #

     2 

     3 ### What's this? ###

     4 

     5 This module implements a simple TNetstring parser and serializer.

     6 TNetString stands for "tagged netstring" and is a modification of Dan

     7 Bernstein's netstrings specification.  TNetstrings allow for the same

     8 data structures as JSON but in a format that is resistant to buffer

     9 overflows and backward compatible with original netstrings.  They make

    10 no assumptions about string contents, allowing for easy transmission of

    11 ascii and binary data mixed with strongly typed values.

    12 

    13 See http://cr.yp.to/proto/netstrings.txt and http://tnetstrings.org/ for

    14 additional information.

    15 

    16 

    17 ### Installation ###

    18 

    19 The easiest way to install this module is via the nimble package manager, 

    20 by simply running 'nimble install tnetstring'.

    21 

    22 Alternatively, you can fetch the 'tnetstring.nim' file yourself, and put it in a place of your choosing.

    23 

    24 ### Usage ###

    25 

    26 ```

    27 #!nimrod

    28 import tnetstring

    29 

    30   let

    31       tnetstr = "52:4:test,3:1.3^4:key2,4:true!6:things,12:1:1#1:2#1:3#]}"

    32       tnetobj = parse_tnetstring( tnetstr )

    33 

    34   # tnetobj is now equivalent to the structure:

    35   # @[(key: test, val: 1.3), (key: key2, val: true), (key: things, val: @[1, 2, 3])]

    36 

    37   assert( tnetobj.kind == TNetstringObject )

    38   echo tnetobj[ "test" ]

    39   echo tnetobj[ "key2" ]

    40   for item in tnetobj[ "things" ]:

    41       echo item

    42 ```

    43 

    44 Results in:

    45 

    46 ```

    47 #!nimrod

    48   1.3

    49   true

    50   1

    51   2

    52   3

    53 ```

    54 

    55 This module can also be used to reasonably create a serialized

    56 TNetstring, suitable for network transmission:

    57 

    58 ```

    59 #!nimrod

    60    let

    61        number  = 1000

    62        list    = @[ "thing1", "thing2" ]

    63        tnettop = newTNetstringArray() # top-level array

    64        tnetsub = newTNetstringArray() # sub array

    65    

    66    tnettop.add( newTNetstringInt(number) )

    67    for item in list:

    68        tnetsub.add( newTNetstringString(item) )

    69    tnettop.add( tnetsub )

    70    

    71    # Equivalent to: @[1000, @[thing1, thing2]]

    72    echo dump_tnetstring( tnettop )

    73 ```

    74 

    75 Results in:

    76 

    77 ```

    78 #!nimrod

    79    29:4:1000#18:6:thing1,6:thing2,]]

    80 ```