Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A Ruby implementation of tagged netstrings, a simple data interchange format better suited to low-level network communication than JSON.
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.gitignore
Gemfile
HISTORY.rdoc
MIT-LICENSE
README.rdoc
Rakefile
tnetstring.gemspec

README.rdoc

tnetstring-rb

Tagged netstrings were conceived by Zed Shaw as a convenient text format for exchanging small amounts of data over the network, based on Dan Bernstein's earlier idea, netstrings. They are meant as an alternative to JSON that are easier to handle in low-level network code and simpler to implement.

The following set of intended characteristics of tagged netstrings is excerpted from the official specification:

  • Trivial to parse in every language without making errors.

  • Resistant to buffer overflows and other problems.

  • Fast and low resource intensive.

  • Makes no assumptions about string contents and can store binary data without escaping or encoding them.

  • Backward compatible with original netstrings.

  • Transport agnostic, so it works with streams, messages, files, anything that's 8-bit clean.

Tagged netstrings support the following primitives: strings, integers, booleans (true or false), null (or nil), lists (arrays), and dictionaries (hashes).

Please see the official spec tnetstrings.org for further detail.

Examples

Given a string in tnetstring format, it can be parsed like so:

str = '5:12345#'
TNetstring.parse(str)

#=> [12345, '']

This returns a tuple that contains the parsed object and any remaining string input.

Encoding an object as a tnetstring is similarly straightforward:

int = 12345
TNetstring.encode(int)

#=> '5:12345#'

Please see the specs in this project for more examples.

Installation

It's a gem, so do the usual:

gem install tnetstring

Attribution

The initial implementation was a port of Zed's first (pre-standardization) tnetstrings implementation in Python.

The Future

Before going 1.0 the library will be converted to a native gem for performance reasons. A native Java/JRuby implementation is planned as well. The current pure Ruby gem may be ported to a tnetstring-pure library.

Something went wrong with that request. Please try again.