This library is no longer maintained. If you are interested in using or maintaining, please fork it and update according to the license.
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 intended primarily as a wire protocol for transferring data between applications. If storing Transit data durably, readers and writers are expected to use the same version of Transit and you are responsible for migrating/transforming/re-storing that data when and if the transit format changes.
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.
See https://rubygems.org/gems/transit-ruby
gem install transit-ruby
# 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
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
Implement from_rep(rep)
method. For example:
class PointReadHandler
def from_rep(rep)
Point.new(*rep)
end
end
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.
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 | Integer | Integer | 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("2**64") | #<BigDecimal:7f9e6d33c558> |
big integer | Integer | Integer | 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) |
- MRI 2.1.10, 2.2.7, 2.3.4, 2.4.0, 2.4.1, 2.6.0..3
- JRuby 1.7.13..16
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.