Oct 10, 2018 Tags: crystal, devblog, programming
Yet another Crystal shard announcement: I’m releasing netstring.cr, a tiny library for parsing netstrings.
Netstrings are a barebones string serialization format,
containing just enough information to parse a string of exactly N bytes. Every netstring
begins with an (ASCII) length prefix, followed by a literal ‘:’, followed by exactly length bytes
of data, followed by a literal ‘,’.
So,
1
6:foobar,
parses as “foobar”. Because they specify their exact length, netstrings are trivially nestable:
1
12:3:foo,3:bar,,
parses as “3:foo,3:bar,”, each of which can then be parsed individually.
The easiest way to install netstring.cr is via Crystal’s shards dependency manager.
You can find the relevant steps in the repository
README.
To instantiate a netstring, use Netstring.parse with either a source String or IO:
1
2
3
4
5
6
7
require "netstring"
ns1 = Netstring.parse "22:parsing from a string!,"
io = IO::Memory.new("19:parsing from an IO!,")
ns2 = Netstring.parse io
By default, netstring.cr limits the size of a netstring to Netstring::NETSTRING_MAX
(999999999, taken from djb’s reference implementation). Users can make this either higher or
lower by passing their own maximum to parse:
1
2
3
4
ns3 = Netstring.parse "5:apple,", max: 6
# parse error!
ns4 = Netstring.parse "8:cucumber,", max: 6
Both parse forms return a new Netstring instance, which provides three simple methods for
querying the state of a netstring: #size, #data, and #to_s:
1
2
3
4
5
6
ns1.size # => 22
ns2.data # => Bytes[112, 97, 114, 115, ...]
# encodes to UTF-8, so make sure your netstring is valid unicode!
ns1.to_s # => "parsing from a string!"
Thanks for reading!