author | Mahlon E. Smith <mahlon@martini.nu> |
Mon, 08 Oct 2018 12:53:05 -0700 | |
changeset 11 | c302a311cedf |
parent 8 | 67c1c0c716e8 |
permissions | -rw-r--r-- |
3
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
1 |
# README # |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
2 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
3 |
### What's this? ### |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
4 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
5 |
This module implements a simple TNetstring parser and serializer. |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
6 |
TNetString stands for "tagged netstring" and is a modification of Dan |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
7 |
Bernstein's netstrings specification. TNetstrings allow for the same |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
8 |
data structures as JSON but in a format that is resistant to buffer |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
9 |
overflows and backward compatible with original netstrings. They make |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
10 |
no assumptions about string contents, allowing for easy transmission of |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
11 |
ascii and binary data mixed with strongly typed values. |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
12 |
|
8
67c1c0c716e8
README.md edited online with Bitbucket
Mahlon E. Smith <mahlon@martini.nu>
parents:
3
diff
changeset
|
13 |
See http://cr.yp.to/proto/netstrings.txt and http://tnetstrings.info/ for |
3
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
14 |
additional information. |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
15 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
16 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
17 |
### Installation ### |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
18 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
19 |
The easiest way to install this module is via the nimble package manager, |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
20 |
by simply running 'nimble install tnetstring'. |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
21 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
22 |
Alternatively, you can fetch the 'tnetstring.nim' file yourself, and put it in a place of your choosing. |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
23 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
24 |
### Usage ### |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
25 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
26 |
``` |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
27 |
#!nimrod |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
28 |
import tnetstring |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
29 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
30 |
let |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
31 |
tnetstr = "52:4:test,3:1.3^4:key2,4:true!6:things,12:1:1#1:2#1:3#]}" |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
32 |
tnetobj = parse_tnetstring( tnetstr ) |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
33 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
34 |
# tnetobj is now equivalent to the structure: |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
35 |
# @[(key: test, val: 1.3), (key: key2, val: true), (key: things, val: @[1, 2, 3])] |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
36 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
37 |
assert( tnetobj.kind == TNetstringObject ) |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
38 |
echo tnetobj[ "test" ] |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
39 |
echo tnetobj[ "key2" ] |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
40 |
for item in tnetobj[ "things" ]: |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
41 |
echo item |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
42 |
``` |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
43 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
44 |
Results in: |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
45 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
46 |
``` |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
47 |
#!nimrod |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
48 |
1.3 |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
49 |
true |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
50 |
1 |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
51 |
2 |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
52 |
3 |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
53 |
``` |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
54 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
55 |
This module can also be used to reasonably create a serialized |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
56 |
TNetstring, suitable for network transmission: |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
57 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
58 |
``` |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
59 |
#!nimrod |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
60 |
let |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
61 |
number = 1000 |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
62 |
list = @[ "thing1", "thing2" ] |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
63 |
tnettop = newTNetstringArray() # top-level array |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
64 |
tnetsub = newTNetstringArray() # sub array |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
65 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
66 |
tnettop.add( newTNetstringInt(number) ) |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
67 |
for item in list: |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
68 |
tnetsub.add( newTNetstringString(item) ) |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
69 |
tnettop.add( tnetsub ) |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
70 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
71 |
# Equivalent to: @[1000, @[thing1, thing2]] |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
72 |
echo dump_tnetstring( tnettop ) |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
73 |
``` |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
74 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
75 |
Results in: |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
76 |
|
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
77 |
``` |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
78 |
#!nimrod |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
79 |
29:4:1000#18:6:thing1,6:thing2,]] |
ef9f89362aac
README.md edited online with Bitbucket
Mahlon Smith <mahlon@martini.nu>
parents:
diff
changeset
|
80 |
``` |