protobuf-activerecord 1.0.1 → 1.0.2

data/README.md

@@ -18,7 +18,97 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Protobuf Active Record's functionality is contained within the `Protoable` module. To endow your Active Record models with the protoable behaviour, simply include it into your model:
+
+```Ruby
+
+	class User < ActiveRecord::Base
+	  include Protoable
+
+	  # Your awesome methods...
+	  #
+	end
+
+```
+
+Now you can pass protobuf messages to your user model just like you would attributes. Protoable will take care of converting the protobuf message to attributes and continue on with Active Record's normal behavior.
+
+### Field/Attribute mapping
+
+Just like Active Record maps database columns to your model's attributes, Protoable maps protobuf fields to your model's attributes.
+
+Given a table that looks like this:
+
+```Ruby
+
+	create_table :users do |t|
+	  t.string :first_name
+	  t.string :last_name
+	  t.string :email
+	  t.integer :account_id
+
+	  t.timestamps
+	end
+
+```
+
+and a protobuf message that looks like this:
+
+```Ruby
+
+	class UserMessage < ::Protobuf::Message
+	  optional ::Protobuf::Field::StringField, :first_name, 1
+	  optional ::Protobuf::Field::StringField, :last_name, 2
+	  optional ::Protobuf::Field::StringField, :email, 3
+	  optional ::Protobuf::Field::IntegerField, :account_id, 4
+	end
+
+```
+
+Protoable will map the `first_name`, `last_name`, `email`, & `account_id` columns, skipping the timestamp columns. Repeated fields and fields that are nil will not be mapped.
+
+**Dates**
+
+Since Protocol Buffer messages don't support sending date, time, or datetime fields, Protoable expects date, time, and datetime fields to be sent as integers. Just like Active Record handles translating Ruby dates, times, and datetimes into the proper database column types, Protoable will handle converting dates, times, and dateimes to and from integers mapping protobuf message fields.
+
+Picking up our users table example again, if you wanted to add a `created_at` field to your protobuf message, if you add it as an integer field, Protoable will handle the conversions for you:
+
+```Ruby
+
+	class UserMessage < ::Protobuf::Message
+	  optional ::Protobuf::Field::StringField, :first_name, 1
+	  optional ::Protobuf::Field::StringField, :last_name, 2
+	  optional ::Protobuf::Field::StringField, :email, 3
+	  optional ::Protobuf::Field::IntegerField, :account_id, 4
+
+	  # Add a datetime field as an integer and Protoable will map it for you
+	  optional ::Protobuf::Field::IntegerField, :created_at, 5
+	end
+
+```
+
+**Mass-assignment**
+
+If a model has protected attributes defined, Protoable will skip any fields that map to them. Likewise, if there are accessible attributes defined, only they will be mapped.
+
+### Persistence
+
+Protoable doesn't alter Active Record's normal persistence methods. It simply adds to ability to pass protobuf messages to them in place of an attributes hash.
+
+### Serialization
+
+In addition to mapping protobuf message fields to Active Record objects when creating or updating records, Protoable also provides the ability to serialize Active Record objects to protobuf messages. Simply tell Protoable the protobuf message that should be used and it will take care of the rest:
+
+```Ruby
+
+	class User < ActiveRecord::Base
+    # Configures Protoable to use the UserMessage class and adds a :to_proto method.
+	  protobuf_message :user_message
+	end
+
+```
+
+Once the desired protobuf message has been specified, Protoable adds a `to_proto` method to the model. Calling `to_proto` will automatically convert the model to the specified protobuf message using the same attribute to field mapping it uses to create and update objects from protobuf messages.
 
 ## Contributing
 

data/lib/protoable/fields.rb

@@ -10,6 +10,9 @@ module Protoable
         class << self
           attr_accessor :_protobuf_columns, :_protobuf_column_types,
             :_protobuf_column_transformers, :_protobuf_field_converters
+
+          alias_method :convert_field_to_column, :convert_field
+          alias_method :transform_column_from_proto, :transform_column
         end
 
         @_protobuf_columns = {}

data/lib/protoable/persistence.rb

@@ -51,21 +51,39 @@ module Protoable
         attributes
       end
 
+      # :nodoc:
+      def create(attributes, options = {}, &block)
+        attributes = attributes_from_proto(proto) if attributes.is_a?(::Protobuf::Message)
+
+        super(attributes, options)
+      end
+
+      # :nodoc:
+      def create!(attributes, options = {}, &block)
+        attributes = attributes_from_proto(proto) if attributes.is_a?(::Protobuf::Message)
+
+        super(attributes, options)
+      end
+
       # Creates an object from the given protobuf message, if it's valid. The
       # newly created object is returned if it was successfully saved or not.
       #
-      def create_from_proto(proto)
+      def create_from_proto(proto, options = {})
         attributes = attributes_from_proto(proto)
 
         yield(attributes) if block_given?
 
-        record = self.new(attributes)
-
-        record.save! if record.valid?
-        return record
+        self.create(attributes, options)
       end
     end
 
+    # :nodoc:
+    def assign_attributes(attributes, options = {})
+      attributes = attributes_from_proto(proto) if attributes.is_a?(::Protobuf::Message)
+
+      super(attributes, options)
+    end
+
     # Calls up to the class version of the method.
     #
     def attributes_from_proto(proto)
@@ -79,16 +97,29 @@ module Protoable
       destroy
     end
 
+    # :nodoc:
+    def update_attributes(attributes, options = {})
+      attributes = attributes_from_proto(proto) if attributes.is_a?(::Protobuf::Message)
+
+      super(attributes, options)
+    end
+
+    # :nodoc:
+    def update_attributes!(attributes, options = {})
+      attributes = attributes_from_proto(proto) if attributes.is_a?(::Protobuf::Message)
+
+      super(attributes, options)
+    end
+
     # Update a record from a proto message. Accepts an optional block.
     # If block is given, yields the attributes that would be updated.
     #
-    def update_from_proto(proto)
+    def update_from_proto(proto, options = {})
       attributes = attributes_from_proto(proto)
 
       yield(attributes) if block_given?
 
-      assign_attributes(attributes)
-      return valid? ? save! : false
+      update_attributes(attributes, options)
     end
   end
 end

data/lib/protoable/serialization.rb

@@ -7,6 +7,8 @@ module Protoable
       klass.class_eval do
         class << self
           attr_accessor :_protobuf_column_converters, :protobuf_fields
+
+          alias_method :convert_column_to_field, :convert_column
         end
 
         @_protobuf_column_converters = {}

data/lib/protobuf/activerecord/version.rb

@@ -1,5 +1,5 @@
 module Protobuf
   module ActiveRecord
-    VERSION = "1.0.1"
+    VERSION = "1.0.2"
   end
 end

data/spec/protoable/persistence_spec.rb

@@ -78,7 +78,7 @@ describe Protoable::Persistence do
       end
 
       context "when an error occurs while saving" do
-        before { User.any_instance.stub(:save!).and_raise(RuntimeError) }
+        before { User.any_instance.stub(:create).and_raise(RuntimeError) }
 
         it "raises an exception" do
           expect { User.create_from_proto(proto) }.to raise_exception
@@ -112,7 +112,7 @@ describe Protoable::Persistence do
 
   describe "#update_from_proto" do
     it "updates the object with attributes from the given protobuf message" do
-      user.should_receive(:assign_attributes).with(user_attributes)
+      user.should_receive(:assign_attributes).with(user_attributes, {})
       user.update_from_proto(proto)
     end
 
@@ -133,13 +133,13 @@ describe Protoable::Persistence do
 
       context "when saving is successful" do
         it "returns true" do
-          user.stub(:save!).and_return(true)
+          user.stub(:assign_attributes).and_return(true)
           user.update_from_proto(proto).should be_true
         end
       end
 
       context "when an error occurs while saving" do
-        before { user.stub(:save!).and_raise(RuntimeError) }
+        before { user.stub(:assign_attributes).and_raise(RuntimeError) }
 
         it "raises an exception" do
           expect { user.update_from_proto }.to raise_exception

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protobuf-activerecord
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-26 00:00:00.000000000 Z
+date: 2012-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -222,7 +222,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -307556624232627597
+      hash: -2932429429413082945
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -231,7 +231,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -307556624232627597
+      hash: -2932429429413082945
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24