1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
= CBOR for Ruby
This is a Ruby implementation of the CBOR[http://cbor.io] encoding, based on
the (polished) high-performance msgpack-ruby code.
Documentation will follow, but generally, if you replace MessagePack
and msgpack with CBOR and cbor in the text cited from MessagePack
below, you will be on the right track. For a starter:
require 'cbor'
s = [1, 2, 33.5, 4].to_cbor #=> "\x84\x01\x02\xF9P0\x04"
CBOR.decode(s) #=> [1, 2, 33.5, 4]
Use RubyGems to install:
gem install cbor
CBOR is an object representation format defined by the IETF[http://ietf.org].
The specification[http://tools.ietf.org/html/rfc7049]
is an IETF Standards-Track specification
and has been published as RFC 7049.
This is all based on wonderful work by frsyuki, and I have no idea how
to acknowledge him appropriately. This gem is not intended to fork or
supersede MessagePack[http://msgpack.org], which has a vibrant
ecosystem. It is just making use of the high-quality code that is
available in this community. If MessagePack works for you, go for it.
If you need CBOR, you need this.
Todos:
* This code has not yet been fully optimized, so it is still a few
percent slower than msgpack-ruby.
* Properly document things, in particular the classes CBOR::Simple and
CBOR::Tagged. If you check out the source, you can +rake+ +doc+ to
get some documentation in the directory +doc+ (see +index.html+ there).
* Cover more rubies.
* \[✔✔✔✔] tested on MRI (1.9.3, 2.0.0, 2.1.10, 2.2.10, 2.3.7, 2.4.4 and 2.5.1).
* (\[✔] There now also is some basic MRI 1.8.7 compatibility, however 1.8.7 does not support differentiation between byte and text strings.)
* \[✔] tested on Rubinius 2.4.1.
* \[_] Publish the pure-ruby version and make it work the same way on JRuby.
* Find and implement good ways to offer CBOR's indefinite length
("streaming") capability at the Ruby API level. (Decoding is fully
supported, just no streaming or indefinite length encoding.)
* Rename some of the internals from msgpack to cbor. Right now, much
of the code still uses the name msgpack in its identifiers, to
facilitate merging upstream fixes. (The msgpack and cbor gems
coexist nicely in one MRI instance due to the magic in +renamer.h+.)
Same Apache 2.0 License applies to the changes as to the original.
For the changes:
Author:: Carsten Bormann <cabo@tzi.org>
Copyright:: Copyright (c) 2013, 2014 Carsten Bormann
License:: Apache License, Version 2.0
{<img src="https://travis-ci.org/cabo/cbor-ruby.svg?branch=master" />}[https://travis-ci.org/cabo/cbor-ruby] {<img src="https://badge.fury.io/rb/cbor.svg" alt="Gem Version" />}[http://badge.fury.io/rb/cbor]
For the original, see below.
= MessagePack
MessagePack[http://msgpack.org] is an efficient binary serialization format.
It lets you exchange data among multiple languages like JSON but it's faster and smaller.
For example, small integers (like flags or error code) are encoded into a single byte,
and typical short strings only require an extra byte in addition to the strings themselves.
If you ever wished to use JSON for convenience (storing an image with metadata) but could
not for technical reasons (binary data, size, speed...), MessagePack is a perfect replacement.
require 'msgpack'
msg = [1,2,3].to_msgpack #=> "\x93\x01\x02\x03"
MessagePack.unpack(msg) #=> [1,2,3]
Use RubyGems to install:
gem install msgpack
or build msgpack-ruby and install:
bundle
rake
gem install --local pkg/msgpack
= Use cases
* Store objects efficiently serialized by msgpack on memcached or Redis
* In fact Redis supports msgpack in EVAL-scripts[http://redis.io/commands/eval]
* Upload data in efficient format from mobile devices such as smartphones
* MessagePack works on iPhone/iPad and Android. See also Objective-C[https://github.com/msgpack/msgpack-objectivec] and Java[https://github.com/msgpack/msgpack-java] implementations
* Design a portable protocol to communicate with embedded devices
* Check also Fluentd[http://fluentd.org/] which is a log collector which uses msgpack for the log format (they say it uses JSON but actually it's msgpack, which is compatible with JSON)
* Exchange objects between software components written in different languages
* You'll need a flexible but efficient format so that components exchange objects while keeping compatibility
= Portability
MessagePack for Ruby should run on x86, ARM, PowerPC, SPARC and other CPU architectures.
And it works with MRI (CRuby) and Rubinius.
Patches to improve portability is highly welcomed.
= Serializing objects
Use *MessagePack.pack* or *to_msgpack*:
require 'msgpack'
msg = MessagePack.pack(obj) # or
msg = obj.to_msgpack
== Streaming serialization
Packer provides advanced API to serialize objects in streaming style:
# serialize a 2-element array [e1, e2]
pk = MessagePack::Packer.new(io)
pk.write_array_header(2).write(e1).write(e2).flush
See {API reference}[http://ruby.msgpack.org/MessagePack/Packer.html] for details.
= Deserializing objects
Use *MessagePack.unpack*:
require 'msgpack'
obj = MessagePack.unpack(msg)
== Streaming deserialization
Unpacker provides advanced API to deserialize objects in streaming style:
# deserialize objects from an IO
u = MessagePack::Unpacker.new(io)
u.each do |obj|
# ...
end
or event-driven style which works well with EventMachine:
# event-driven deserialization
def on_read(data)
@u ||= MessagePack::Unpacker.new
@u.feed_each(data) {|obj|
# ...
}
end
See {API reference}[http://ruby.msgpack.org/MessagePack/Unpacker.html] for details.
= Buffer API
MessagePack for Ruby provides a buffer API so that you can read or write data by hand, not via Packer or Unpacker API.
This {MessagePack::Buffer}[http://ruby.msgpack.org/MessagePack/Buffer.html] is backed with a fixed-length shared memory pool which is very fast for small data (<= 4KB),
and has zero-copy capability which significantly affects performance to handle large binary data.
= How to build and run tests
Before building msgpack, you need to install bundler and dependencies.
gem install bundler
bundle install
Then, you can run the tasks as follows:
* Build
bundle exec rake build
* Run tests
bundle exec rake spec
* Generating docs
bundle exec rake doc
= Copyright
Author:: Sadayuki Furuhashi <frsyuki@gmail.com>
Copyright:: Copyright (c) 2008-2013 Sadayuki Furuhashi
License:: Apache License, Version 2.0
|
