README.md

TJSON for Ruby

A Ruby implementation of TJSON: Tagged JSON with Rich Types.

TJSON is a microformat which supplements JSON with an extended set of data types by supplying a type "tag" embedded in object member names:

{
  "array-example:A<O>": [
    {
      "string-example:s": "foobar",
      "binary-data-example:d": "QklOQVJZ",
      "float-example:f": 0.42,
      "int-example:i": "42",
      "timestamp-example:t": "2016-11-06T22:27:34Z",
      "boolean-example:b": true
    }
  ],
  "set-example:S<i>": [1, 2, 3]
}

Help and Discussion

Have questions? Want to suggest a feature or change?

• TJSON Gitter: web-based chat
• TJSON Google Group: join via web or email ([email protected])

Requirements

This library is tested against the following Ruby versions:

• 2.4
• 2.5
• 2.6
• JRuby

Other Ruby versions may work, but are not officially supported.

Installation

Add this line to your application's Gemfile:

gem 'tjson'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tjson

API

TJSON.parse

To parse a TJSON document, use the TJSON.parse method:

>> TJSON.parse('{"foo:s":"bar"}')
=> {"foo"=>"bar"}

TJSON.generate

To generate TJSON from Ruby objects, use the TJSON.generate method:

puts TJSON.generate({"foo" => "bar"})
# {"foo:s:"bar"}

For better formatting, use the TJSON.pretty_generate method:

puts TJSON.pretty_generate({"array-example" => [{"string-example" => "foobar", "binary-example" => "BINARY".b, "float-example" => 0.42, "int-example" => 42, "timestamp-example" => Time.now}]})
# {
#   "array-example:A<O>": [
#     {
#       "string-example:s": "foobar",
#       "binary-example:d": "QklOQVJZ",
#       "float-example:f": 0.42,
#       "int-example:i": "42",
#       "timestamp-example:t": "2016-11-06T22:27:34Z"
#     }
#   ]
# }

Type Conversions

The table below shows how TJSON tags map to Ruby types:

Tag	Ruby Type
b	true or false
d	String with Encoding::ASCII_8BIT (a.k.a. Encoding::BINARY)
f	Float
i	Integer (Fixnum or Bignum on Ruby <2.4 )
u	Integer (Fixnum or Bignum on Ruby <2.4 )
s	String with Encoding::UTF_8
t	Time
A	Array
O	TJSON::Object (a subclass of ::Hash)
S	Set

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tjson/tjson-ruby

License

Copyright (c) 2017 Tony Arcieri. Distributed under the MIT License. See LICENSE.txt for further details.