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.
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.
$ 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.
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 # trueProtocol 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
endThis 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 => '[email protected]')
open("group1.test", "wb") do |f|
group.serialize(f)
end- 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
- extensions
- packed option (could be useful)
- accessing custom options
Brian Palmer (http://github.com/codekitchen)
https://github.com/codekitchen/ruby-protocol-buffers
See the LICENSE file included with the distribution for licensing and copyright details.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent