ruby-protocol-buffers 1.2.3.beta2 → 1.3.0

data/README.md

@@ -6,14 +6,16 @@ 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.
+buffers defined by these modules.
 
-This library is heavily optimized for encoding and decoding speed. There is a
-small C extension available in the ext/ dir that will improve performance even
-further, but it is currently disabled to avoid rubygems having to compile a
-native extension. TODO: anybody know if we can make this optional?
+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
@@ -21,15 +23,109 @@ code is generated.
 
 ## Installation
 
-You'll need protoc version >= 2.2 (the Google Protocol Buffer compiler)
-installed in the environment where you will be compiling protocol buffers. This
-is only needed for compiling, you don't need it installed to use the generated
-`.pb.rb` files. You do need this Ruby library installed to use the
-`.pb.rb` files, for the runtime support.
+    $ 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.
+
+## 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:
+
+```ruby
+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.
 
-If you use RubyGems, you can install via:
+```ruby
+require 'protocol_buffers'
 
-    $ sudo gem install ruby-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`.
+
+```ruby
+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
 
@@ -53,16 +149,6 @@ If you use RubyGems, you can install via:
 * deprecated protocol features (e.g. groups)
 * the unsupported options (java_*, optimize_for, message_set_wire_format, deprecated)
 
-## Simple Usage Example
-
-    $ echo "package Test; message MyMessage { optional string myField = 1; }" > test.proto
-    $ bin/ruby-protoc test.proto
-    $ irb -I./lib -rtest.pb
-    > msg = Test::MyMessage.new(:myField => 'zomgkittenz')
-    => #<Test::MyMessage myField="zomgkittenz">
-    > Test::MyMessage.parse(msg.to_s) == msg
-    => true
-
 ## Authors
 
 Brian Palmer (http://github.com/codekitchen)

data/VERSION

@@ -1 +1 @@
-1.2.3.beta2
+1.3.0

data/ruby-protocol-buffers.gemspec

@@ -18,9 +18,10 @@ Gem::Specification.new do |s|
 
   s.extra_rdoc_files << "Changelog.md"
 
-  s.add_development_dependency "rspec", "~> 2.5"
   s.add_development_dependency "autotest-standalone"
   s.add_development_dependency "autotest-growl"
+  s.add_development_dependency "rake"
   s.add_development_dependency "rcov"
+  s.add_development_dependency "rspec", "~> 2.5"
   s.add_development_dependency "yard"
 end

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: ruby-protocol-buffers
 version: !ruby/object:Gem::Version
-  version: 1.2.3.beta2
-  prerelease: 6
+  version: 1.3.0
+  prerelease: 
 platform: ruby
 authors:
 - Brian Palmer
@@ -11,26 +11,26 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-19 00:00:00.000000000 Z
+date: 2013-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: autotest-standalone
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ~>
+    - - ! '>='
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: autotest-standalone
+  name: autotest-growl
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -46,7 +46,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: autotest-growl
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -77,6 +77,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.5'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -166,9 +182,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23