Protocol Buffers v3
IMPORTANT This library supports the Protocol Buffers v2 specification. Google has developed official Ruby support for Protobuf v3, the gem is available at https://rubygems.org/gems/google-protobuf. Because there's now an official gem, I have no plans to implement v3 support in this library.
Ruby Protocol Buffers
Protocol Buffers are a way of encoding structured data in an efficient yet extensible format. Google uses Protocol Buffers for almost all of its internal RPC protocols and file formats.
This library has two components: a compiler to turn .proto
definitions
into Ruby modules (extension .pb.rb
), and a runtime to use protocol
buffers defined by these modules.
The compiler relies on Google's C++ based compiler (protoc
) for much of
the heavy lifting -- this has huge advantages in ensuring compatibility and
correctness. If you don't need cross-language interoperability you can
create Message classes directly in ruby, in which case protoc
is not
needed. See "Writing Message Classes Directly" below.
This library is heavily optimized for encoding and decoding speed.
Because this is a tool for generating code, the RDoc documentation is a bit unusual. See the text in the ProtocolBuffers::Message class for details on what code is generated.
Installation
$ gem install ruby-protocol-buffers
If you want to compile .proto files to ruby, you'll need protoc
version >=
2.2 (the Google Protocol Buffer compiler) installed in the environment where
you will be compiling them. You do not need protoc
installed to use the
generated .pb.rb
files.
For greater performance, consider installing the varint gem as well. This optional gem builds a small C extension to make parsing protocol buffers faster. If your application uses a Gemfile, add varint to the Gemfile alongside ruby-protocol-buffers.
Example
Given the file test.proto:
package Test;
message MyMessage {
optional string myField = 1;
}
Compile it to ruby using the command:
$ ruby-protoc test.proto
Then it can be used from ruby code:
require 'test.pb'
msg = Test::MyMessage.new(:myField => 'zomgkittenz')
open("test_msg", "wb") do |f|
msg.serialize(f)
end
encoded = msg.serialize_to_string # or msg.to_s
Test::MyMessage.parse(encoded) == msg # true
Writing Message Classes Directly
Protocol Buffer definitions are often shared between applications written in
different programming languages, and so are normally defined in .proto files
and translated to ruby using the ruby-protoc
binary.
However, it's quite simple to write ProtocolBuffers::Message
classes
directly when a .proto file isn't needed.
require 'protocol_buffers'
class User < ProtocolBuffers::Message
required :string, :name, 1
required :string, :email, 2
optional :int32, :logins, 3
end
class Group < ProtocolBuffers::Message
repeated User, :users, 1
repeated Group, :subgroups, 2
module GroupType
include ProtocolBuffers::Enum
Study = 1
Play = 2
end
optional GroupType, :group_type, 3
end
This code is essentially equivalent to the code ruby-protoc
will generate
if given this .proto file:
message User {
required string name = 1;
required string email = 2;
optional int32 logins = 3;
}
message Group {
repeated User users = 1;
repeated Group subgroups = 2;
enum GroupType {
Study = 1;
Play = 2;
}
optional GroupType group_type = 3;
}
Using a hand-written Message subclass is the same as using a Message class
generated by ruby-protoc
.
group = Group.new(:group_type => Group::GroupType::Play)
group.users << User.new(:name => 'test user', :email => 'test@example.com')
open("group1.test", "wb") do |f|
group.serialize(f)
end
Features
Supported Features
- messages, enums, field types, all basic protobuf features
- packages
- imports
- nested types
- passing on unknown fields when re-serializing a message
- groups
- RPC stubbing
- formatting to and parsing from text format
Currently Unsupported Features
- extensions
- packed option (could be useful)
- accessing custom options
Authors
Brian Palmer (http://github.com/codekitchen)
Source
https://github.com/codekitchen/ruby-protocol-buffers
License
See the LICENSE file included with the distribution for licensing and copyright details.