No description, website, or topics provided.
Ruby Java Shell
Latest commit 064bd94 Mar 15, 2017 @dchelimsky dchelimsky more trusting oj dep
Permalink
Failed to load latest commit information.
benchmarks
bin
build Add build/release script to release both MRI and JRuby versions in one May 3, 2015
dev Update source copyright/license header Jul 11, 2014
ext/com/cognitect/transit/ruby clean up jruby write handler builder Jan 23, 2015
lib
spec Fix cache bug caused by Tag.new("foo") == "foo" Oct 28, 2016
.gitignore
.rspec Extract from prior work by Russ and David Mar 21, 2014
.yard_redcarpet_ext
.yardopts
BUILD.md
CHANGELOG.md
CONTRIBUTING.md
DEV.md update DEV notes Jul 18, 2014
Gemfile Deleted dependency to jruby 1.7.13 since newer version has been released Sep 2, 2014
Jarfile
LICENSE
README.md
Rakefile Improve tasks for signing the transit-ruby gem (MRI only) May 4, 2015
TODO.org update TODO Jul 19, 2014
transit-ruby.gemspec more trusting oj dep Mar 15, 2017

README.md

transit-ruby

Transit is a data format and a set of libraries for conveying values between applications written in different languages. This library provides support for marshalling Transit data to/from Ruby.

Rationale
API docs
Specification

This implementation's major.minor version number corresponds to the version of the Transit specification it supports.

NOTE: Transit is a work in progress and may evolve based on feedback. As a result, while Transit is a great option for transferring data between applications, it should not yet be used for storing data durably over time. This recommendation will change when the specification is complete.

Contributing

This library is open source, developed internally by Cognitect. We welcome discussions of potential problems and enhancement suggestions on the transit-format mailing list. Issues can be filed using GitHub issues for this project. Because transit is incorporated into products and client projects, we prefer to do development internally and are not accepting pull requests or patches.

Releases and Dependency Information

See https://rubygems.org/gems/transit-ruby

Install

gem install transit-ruby

Basic Usage

# io can be any Ruby IO

writer = Transit::Writer.new(:json, io) # or :json-verbose, :msgpack
writer.write(value)

reader = Transit::Reader.new(:json, io) # or :msgpack
reader.read

# or

reader.read {|val| do_something_with(val)}

For example:

irb(2.1.1): io = StringIO.new('', 'w+')
==========> #<StringIO:0x007faab2ec3970>
irb(2.1.1): writer = Transit::Writer.new(:json, io)
==========> #<Transit::Writer:0x007faab2e8c1c8 @marshaler=#<Transit::JsonMarshaler:0x007faab2e1a168..........(snip)..........
irb(2.1.1): writer.write("abc")
==========> nil
irb(2.1.1): writer.write(123456789012345678901234567890)
==========> nil
irb(2.1.1): io.string
==========> "[\"~#'\",\"abc\"]\n[\"~#'\",\"~n123456789012345678901234567890\"]\n"
irb(2.1.1): reader = Transit::Reader.new(:json, StringIO.new(io.string))
==========> #<Transit::Reader:0x007faab2db48e0 @reader=#<Transit::JsonUnmarshaler:0x007faab2dae030 @..........(snip)..........
irb(2.1.1): reader.read {|val| puts val}
abc
123456789012345678901234567890

Custom Handlers

Custom Write Handlers

Implement tag, rep(obj) and string_rep(obj) methods. For example:

Point = Struct.new(:x,:y) do
  def to_a; [x,y] end
end

class PointWriteHandler
  def tag(_) "point" end
  def rep(o) o.to_a  end
  def string_rep(_) nil end
end

Custom Read Handlers

Implement from_rep(rep) method. For example:

class PointReadHandler
  def from_rep(rep)
    Point.new(*rep)
  end
end

Example Usage

io = StringIO.new('', 'w+')
writer = Transit::Writer.new(:json, io,
                             :handlers => {Point => PointWriteHandler.new})
writer.write(Point.new(37,42))

p io.string.chomp
#=> "[\"~#point\",[37,42]]"

reader = Transit::Reader.new(:json, StringIO.new(io.string),
                             :handlers  => {"point" => PointReadHandler.new})
p reader.read
#=> #<struct Point x=37, y=42>

See Transit::WriteHandlers for more info.

Default Type Mapping

Transit type Write accepts Read returns Example(write) Example(read)
null nil nil nil nil
string String String "abc" "abc"
boolean true, false true, false false false
integer Fixnum, Bignum Fixnum, Bignum 123 123
decimal Float Float 123.456 123.456
keyword Symbol Symbol :abc :abc
symbol Transit::Symbol Transit::Symbol Transit::Symbol.new("foo") #<Transit::Symbol "foo">
big decimal BigDecimal BigDecimal BigDecimal.new("2**64") #<BigDecimal:7f9e6d33c558>
big integer Fixnum, Bignum Fixnum, Bignum 2**128 340282366920938463463374607431768211456
time DateTime, Date, Time DateTime DateTime.now #<DateTime: 2014-07-15T15:52:27+00:00 ((2456854j,57147s,23000000n),+0s,2299161j)>
uri Addressable::URI, URI Addressable::URI Addressable::URI.parse("http://example.com") #<Addressable::URI:0x3fc0e20390d4 URI:http://example.com>
uuid Transit::UUID Transit::UUID Transit::UUID.new #<Transit::UUID "defa1cce-f70b-4ddb-bb6e-b6ac817d8bc8">
char Transit::TaggedValue String Transit::TaggedValue.new("c", "a") "a"
array Array Array [1, 2, 3] [1, 2, 3]
list Transit::TaggedValue Array Transit::TaggedValue.new("list", [1, 2, 3]) [1, 2, 3]
set Set Set Set.new([1, 2, 3]) #<Set: {1, 2, 3}>
map Hash Hash {a: 1, b: 2, c: 3} {:a=>1, :b=>2, :c=>3}
bytes Transit::ByteArray Transit::ByteArray Transit::ByteArray.new("base64") base64
link Transit::Link Transit::Link Transit::Link.new(Addressable::URI.parse("http://example.org/search"), "search") #<Transit::Link:0x007f81c405b7f0 @values={"href"=>#<Addressable::URI:0x3fc0e202dfb8 URI:http://example.org/search>, "rel"=>"search", "name"=>nil, "render"=>nil, "prompt"=>nil}>

Additional types (not required by the transit-format spec)

Semantic type Write accepts Read returns Example(write) Example(read)
ratio Rational Rational Rational(1, 3) Rational(1, 3)

Supported Rubies

  • MRI 1.9.3, 2.0.0, 2.1.0, 2.1.1, 2.1.2
  • JRuby 1.7.13..16

Copyright and License

Copyright © 2014 Cognitect

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.