protobuf-activerecord 2.0.0.rc1 → 2.0.0

data/README.md

@@ -79,10 +79,6 @@ class UserMessage < ::Protobuf::Message
 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.
-
 ### Creating/Updating
 
 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.
@@ -102,27 +98,61 @@ 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.
 
-### Field & attribute converters
+### Choosing serializable fields
+
+Protoable also provides a mechanism for choosing which fields should be included when serializing objects to protobuf messages by passing additional options to `protobuf_message`:
+
+```Ruby
+class User < ActiveRecord::Base
+  include Protoable
+
+  # Passing :only => ... configures Protoable to only serialize the given fields
+  protobuf_message :user_message, :only => [ :first_name, :last_name, :email ]
+end
+```
+
+This will only include the first_name, last_name, and email fields.
+
+Conversely, the `:except` option allows the fields that should be excluded to be specified.
+
+```Ruby
+class User < ActiveRecord::Base
+  include Protoable
 
-Protoable will handle regular field conversions out of the box, but for those times when custom conversions are needed, they can be defined with the `convert_field` and `protoable_attribute` methods. Field converters are used when creating or updating objects from a protobuf message and attribute converters are used when serializing objects to protobuf messages.
+  # Passing :except => ... configures Protoable to serialize everything except the given fields
+  protobuf_message :user_message, :except => [ :account_id, :created_at ]
+end
+```
 
-`convert_field` and `protoable_attribute` both take the name of the field/attribute being converted and a method name or callable (lambda or proc). when converting that field, calls the given callable, passing it the value of the field being converted.
+This does pretty much the same thing, but from a different perspective.
 
-**Converting fields**
+`to_proto` also accepts these options, so you can override the class-level serializable fields on a per-instance basis:
+
+```Ruby
+user.to_proto(:only => :email) # Only the email
+user.to_proto(:except => :email) # Everthing except the email
+user.to_proto(:include => :email) # Start with the class-level settings, but add email
+```
+
+### Serializing deprecated fields
+
+By default, Protoaable includes deprecated fields when mapping protobuf message to Active Record objects. To exclude deprecated fields, simply pass the `:deprecated` option:
 
 ```Ruby
 class User < ActiveRecord::Base
   include Protoable
 
-  # Calls :map_status_from_proto when creating/updating objects, passing it the
-  # value of the status field from the protobuf message.
-  def self.map_status_from_proto(field_value)
-    # Some custom mapping
-  end
-  convert_field :status, :map_status_from_proto
+  # Passing :deprecated => false configures Protoable to exclude deprecated fields.
+  protobuf_message :user_message, :deprecated => false
 end
 ```
 
+### Field transformers
+
+Field transformers are used when serializing objects to protobuf messages. Protoable will handle regular field mapping and conversions out of the box, but for those times when fields don't map directly to attributes or custom behavior is needed, Protoable provides the `field_from_record` method.
+
+`field_from_record` takes the name of the field being transformed and a method name or callable (lambda or proc). When transforming that field, it calls the given callable, passing it the object being serialized.
+
 **Converting attributes**
 
 ```Ruby
@@ -130,8 +160,8 @@ class User < ActiveRecord::Base
   include Protoable
 
   # Calls the lambda when serializing objects to protobuf messages, passing it
-  # the value of the status attribute.
-  protoable_attribute :status, lambda { |attribute_value| attribute_value_.to_s }
+  # the object being serialized.
+  field_from_record :status, lambda { |object_being_serlialized| # Some custom behavior }
 end
 ```
 
@@ -192,7 +222,7 @@ User.search_scope(request)
 User.limit(10).search_scope(request)
 ```
 
-Protoable also provides some aliases for the `search_scope` method in the event that you'd like something a little more descriptive. `by_fields`, `from_proto`, and `scope_from_proto` are all aliases of `search_scope`.
+Protoable also provides some aliases for the `search_scope` method in the event that you'd like something a little more descriptive: `by_fields` and `scope_from_proto` are all aliases of `search_scope`.
 
 ## Contributing
 

data/lib/protobuf/activerecord/protoable/serialization.rb

@@ -92,7 +92,7 @@ module Protoable
       #   protobuf_message :user_message
       #   protobuf_message "UserMessage"
       #   protobuf_message "Namespaced::UserMessage"
-      #   protobuf_message :user_message, :only => :guid, :name
+      #   protobuf_message :user_message, :only => [ :guid, :name ]
       #   protobuf_message :user_message, :except => :email_domain
       #   protobuf_message :user_message, :except => :email_domain, :deprecated => false
       #
@@ -146,13 +146,20 @@ module Protoable
     end
 
     # Extracts attributes that correspond to fields on the specified protobuf
-    # message, performing any necessary column conversions on them.
+    # message, performing any necessary column conversions on them. Accepts a
+    # hash of options for specifying which fields should be serialized.
+    #
+    # Examples:
+    #   fields_from_record(:only => [ :guid, :name ])
+    #   fields_from_record(:except => :email_domain)
+    #   fields_from_record(:include => :email_domain)
+    #   fields_from_record(:except => :email_domain, :deprecated => false)
     #
     def fields_from_record(options = {})
       field_attributes = _filter_field_attributes(options)
       field_attributes += [ options.fetch(:include, []) ]
       field_attributes.flatten!
-      field_attributes.compact
+      field_attributes.compact!
       field_attributes.uniq!
 
       field_attributes = field_attributes.inject({}) do |hash, field|
@@ -170,10 +177,12 @@ module Protoable
 
   private
 
+    # :nodoc:
     def _protobuf_convert_attributes_to_fields(field, value)
       self.class._protobuf_convert_attributes_to_fields(field, value)
     end
 
+    # :nodoc:
     def _protobuf_field_transformers
       self.class._protobuf_field_transformers
     end

data/lib/protobuf/activerecord/protoable/transformation.rb

@@ -118,14 +118,17 @@ module Protoable
         attributes
       end
 
+      # :nodoc:
       def convert_int64_to_time(int64)
         Time.at(int64.to_i)
       end
 
+      # :nodoc:
       def convert_int64_to_date(int64)
         convert_int64_to_time(int64).utc.to_date
       end
 
+      # :nodoc:
       def convert_int64_to_datetime(int64)
         convert_int64_to_time(int64).to_datetime
       end

data/lib/protobuf/activerecord/version.rb

@@ -1,5 +1,5 @@
 module Protobuf
   module ActiveRecord
-    VERSION = "2.0.0.rc1"
+    VERSION = "2.0.0"
   end
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: protobuf-activerecord
 version: !ruby/object:Gem::Version
-  version: 2.0.0.rc1
-  prerelease: 6
+  version: 2.0.0
+  prerelease: 
 platform: ruby
 authors:
 - Adam Hutchison
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-20 00:00:00.000000000 Z
+date: 2013-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -239,13 +239,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1212310308387017285
+      hash: 1889653125462777253
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
+      segments:
+      - 0
+      hash: 1889653125462777253
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25