tracks-attributes 1.0.1 → 1.1.0

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2013 YOURNAME
+Copyright 2013 Leopold O'Donnell
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -6,15 +6,16 @@
 
 # TracksAttributes
 
-TracksAttributes adds the ability to track ActiveRecord and Object level attributes.
+TracksAttributes adds the ability to track ActiveRecord *and* Object level attributes. Beginning at version 1.1.0, it is
+possible to re-hydrate complex object structures that contain *Plain Old Ruby Objects*, or arrays of *POROs*.
 
 Sometimes you just need to know what your accessors are at runtime, like when you're writing a controller that
 needs to return JSON or XML. This module extends ActiveRecord::Base with the *tracks_attributes* class method. Once this has 
 been called the class is extended with the ability to track attributes through *attr_accessor*, *attr_reader*, and *attr_writer*.
-Plain old Ruby classes may also use *TracksAttributes* by including it as a module first.
+*Plain Old Ruby* classes may also use *TracksAttributes* by including it as a module first.
 
 *Note:* The necessity for this gem is born out of the clash between ActiveRecord attribute handling and PORO attributes. Using
-Object#instance_variables just doesn't return the correct list for marshaling data effectively, nor produce values for computed
+Object::instance_variables just doesn't return the correct list for marshaling data effectively, nor produce values for computed
 attributes.
 
 ## Enhanced JSON and XML processing
@@ -23,10 +24,11 @@ Beyond the ability to track your attributes, this gem simplifies your use of con
 Once a class has been extended, it can convert to and from JSON or XML without having to explicitly include attributes.
 
 Example:
+
 ```ruby
 class Person < ActiveRecordBase
   tracks_attributes
-  
+
   attr_accessible :name, :email
   attr_accessor :favorite_food
 end
@@ -43,13 +45,42 @@ fred2.from_json(fred_json)
 puts "#{fred2.name} loves #{fred2.favorite_food}"
 # => Fred loves Brontosaurus Burgers
 ```
+
 Both the JSON and XML take the same options as their Hash and ActiveRecord counterparts so you can still
 use *:only* and *:includes* in your code as needed.
 
-### Current Limitations
+### Re-hydrating Complex Ruby Objects
+
+Classes that have simple types, like <tt>Fixnum</tt> or <tt>String</tt>, can be handled by simply invoking
+<tt>:tracks_attributes</tt> within the class definition. More complex objects require additional information
+to converted from a <tt>Hash</tt> to the correct type of Object. This is done by providing the class in the 
+calls to <tt>attr_accessor</tt>, <tt>attr_reader</tt> and <tt>attr_writer</tt>.
+
+Specify the class of an attribute by providing the option, <tt>:klass</tt>, with the target class as the value.
+
+Example:
+
+```ruby
+  attr_accessor :my_poro_var, :klass => MyPoroClass
+```
 
-If you have a nested set of classes they will still appear as attributes that are Hashes. I hope to
-resolve this in an upcoming version.
+The target class must then provide  class method, <tt>:create</tt>, taking a <tt>Hash</tt> of attributes to
+construct the Object instance.
+
+Here is example from <tt>TracksAttributes::Base</tt>
+
+```ruby
+  class Base
+    include TracksAttributes
+    tracks_attributes
+    
+    def self.create(attributes = {}, options = {})
+      # implentation
+    end
+    
+    # the rest of the class here...
+  end
+```
 
 ## Add Validations To Non Active Record Attributes
 
@@ -59,9 +90,66 @@ To add ActiveModel::Validations to your class just initialize your class with *t
   tracks_attributes :validates => true
 ```
 
+## Use <tt>TracksAttributes::Base</tt> to simplify coding *POROs*
+
+While developers can continue to roll their own *PORO* class, <tt>TracksAttributes::Base</tt> provides a
+quick implementation that tracks attributes, provides validation and works with <tt>TracksAttributes</tt>
+when re-hydrating. Simply inherit from <tt>TracksAttributes::Base</tt> and you are good to go.
+
+Here's an example that shows how simple it is to define:
+
+```ruby
+class Photo < TracksAttributes::Base
+  attr_accessor :title, :filename
+end
+
+class Person < ActiveRecord::Base
+  tracks_attributes
+
+  attr_accessible :name 
+  attr_accessor   :photos, :klass => Photo
+end
+```
+
+Once this has been coded up, it is possible to generate JSON/XML that stream the entire array of
+<tt>PhotoLocation</tt>. More importantly, it is possible to fully re-hydrate a Person, including
+the array of <tt>Photo</tt>. Re-hydration takes place when the <tt>Hash</tt> of attributes is set
+on the Object instance.
+
+Continuing...
+
+```ruby
+# Instance Creation
+photos = [ 
+  Photo.create(:title => 'Hadji and Me', :filename => 'images/hadji_and_me.png'),
+  Photo.create(:title => 'Bandit', :filename => 'images/bandit.png')
+]
+
+johnny_quest        = Person.new(:name => 'Johnny Quest')
+johnny_quest.photos = photos
+
+# Generate the JSON
+jq_json = johnny_quest.to_json
+
+# => {"name":"Johnny Quest","photos":[{"title":"Hadji and Me","filename":"images/hadji_and_me.png"},{"title":"Bandit","filename":"images/bandit.png"}]}
+
+# Later Re-hydrate the JSON
+json_param = params[:person]
+person = Person.new
+person.from_json json_param
+
+puts "Name = #{person.name}, 1st image title = #{person.photos[0].title}"
+# => Johnny Quest, 1st image title = Hadji and Me
+
+```
+
 ## Installation
 
 Add the following to your Gemfile
+    
+    gem 'tracs-attributes
+
+Or from the git repo for the bleeding edge (*feel free to star it :-)*)
 
     gem 'tracks-attributes', :git => "git://github.com/leopoldodonnell/tracks-attributes"
 
@@ -69,4 +157,6 @@ Then call bundle to install it.
 
     > bundle
 
-This project rocks and uses MIT-LICENSE.
+## License
+
+This project rocks and uses MIT-LICENSE. Copyright 2013 Leopold O'Donnell

data/lib/tracks_attributes/attr_info.rb

@@ -0,0 +1,23 @@
+module TracksAttributes
+  ##
+  # Holds the information needed by a class including TracksAttributes
+  # in order to track information that can be effectively used to
+  # re-hydrate instances from JSON or XML
+  class AttrInfo
+    attr_accessor :name, :klass, :is_readable, :is_writeable
+    
+    ##
+    # Props
+    #   * :name - the attribute name
+    #   * :kass - the attribute class
+    #   * :is_readable - true if the attribute is readable
+    #   * :is_writeable - true if the attribute is writeable
+    #
+    def initialize(props = {})
+      self.name   = props[:name]
+      self.klass  = props[:klass]
+      self.is_readable   = props[:is_readable] || true
+      self.is_writeable  = props[:is_writeable] || true
+    end
+  end  
+end

data/lib/tracks_attributes/base.rb

@@ -0,0 +1,41 @@
+module TracksAttributes
+  ##
+  # TracksAttributes::Base is a convienience class that offers
+  # the basic services available through the TracksAttribute module
+  # for plain old ruby objects.
+  #
+  # * it tracks attributes
+  # * it provides <tt>Base::create</tt> to enable re-hydration within the scope
+  #   of a containing class that is being built from JSON or XML
+  # * it includes <tt>ActiveModel::Validations</tt>
+  # 
+  class Base
+    extend ClassMethods
+    include ActiveModel::Validations
+    
+    ##
+    # The standard create class method needed by a class that implements
+    # TracksAttributes during re-hydration.
+    # 
+    # @param [Hash] attributes is Hash with attributes as values to set
+    # as instance variables.
+    # @param [Hash] options to be passed onto the initialize method.
+    #
+    def self.create(attributes = {}, options = {})
+      self.new attributes, options
+    end
+
+    ##
+    # The default :initialize method needed by a class that implements
+    # TracksAttributes during re-hydration.
+    # 
+    # @param [Hash] attributes is Hash with attributes as values to set
+    # as instance variables.
+    # @param [Hash] options to be passed onto the initialize method.
+    #
+    def initialize(attributes = {}, options = {})
+      self.class.tracks_attributes(options) unless self.class.respond_to? :attr_info_for
+      self.all_attributes = attributes
+    end
+  end
+end

data/lib/tracks_attributes/version.rb

@@ -1,3 +1,3 @@
 module TracksAttributes
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

data/lib/tracks_attributes.rb

@@ -1,5 +1,5 @@
 # @author Leo O'Donnell
-
+require 'tracks_attributes/attr_info'
 ##
 # A Module that can be used to extend ActiveRecord or Plain Old Ruby Objects
 # with the ability to track all attributes. It also simplifies streaming to and
@@ -9,6 +9,48 @@
 # This module can also be used as building block for other classes that need to
 # be dynamically aware of their attributes.
 #
+# Instance re-hydration from a Hash/JSON/XML may be simple, or may need more complex handling.
+#
+# In the case of simple re-hydration, attributes are simply assigned their values.
+#
+# When instances have more complex instance variables that need to be made available
+# at run time when re-hydrating, a Class can be specified in the calls to <tt><attr_xxx/tt>
+# with the key <tt>:klass</tt>. During the call to <tt>:attributes=</tt>, the Hash's value
+# is used to consctruct an instance of <tt>klass</tt> if it supplies a <tt>klass::create</tt>
+# class method. If the attribute is an array, the array will be mapped from instances of
+# <tt>Hash</tt> to instances of <tt>klass</tt>
+#
+# *Example:*
+#
+#     class NestedClass
+#       include TracksAttributes
+#       tracks_attributes
+#       
+#       attr_accessor :one, :two
+#       
+#       def self.create(attributes = {})
+#         # code to create an instance of NestedClass
+#       end
+#     end
+#        
+#     class TrackedClass < ActiveRecord::Base
+#       tracks_attributes
+#      
+#       attr_accessible  :foo 
+#       attr_accessor    :nested, :klass => NestedClass
+#     end
+#
+# This example shows an <tt>ActiveRecord::Base</tt> class that has a plain old Ruby Object
+# nested inside that needs to be streamed to and from JSON. It includes the module <tt>TracksAttribues</tt>
+# and implements a <tt>:create</tt> class method.
+#
+# This example could be further simplified by using the <tt>TracksAttributes::Base</tt> class. <tt>NestedClass</tt>
+# would be re-cast as:
+#
+#     class NestedClass < TracksAttributes::Base
+#       attr_accessor :one, :two
+#     end
+#
 module TracksAttributes
   extend ActiveSupport::Concern
   
@@ -26,7 +68,7 @@ module TracksAttributes
     # @see TracksAttributesInternal TracksAttributesInternal for full method list
     def tracks_attributes(options={})
       include TracksAttributesInternal
-      include ActiveModel::Validations if options[:validates]
+      enable_validations if options[:validates]
       self
     end
   end
@@ -35,35 +77,78 @@ module TracksAttributes
     extend ActiveSupport::Concern
 
     included do
-      @tracked_attrs ||= []
+      @tracked_attrs ||= {}
     end
 
     module ClassMethods
-      # override attr_accessor to track accessors for an TracksAttributes
+      
+      # Override attr_accessor to track accessors for an TracksAttributes.
+      # If the last argument may be a <tt>Hash</tt> of options where the
+      # options may be:
+      #
+      # * klass - the Class of the attribute to create when re-hydrating
+      #           the instance from a Hash/JSON/XML
+      #
       def attr_accessor(*vars)
-        @tracked_attrs.concat vars
-        super
+        super *(add_tracked_attrs(true, true, *vars))
       end
 
-      # override attr_reader to track accessors for an TracksAttributes
+      # Override attr_reader to track accessors for an TracksAttributes.
+      # If the last argument may be a <tt>Hash</tt> of options where the
+      # options may be:
+      #
+      # * klass - the Class of the attribute to create when re-hydrating
+      #           the instance from a Hash/JSON/XML
+      #
       def attr_reader(*vars)
-        @tracked_attrs.concat vars
-        super
+        super *(add_tracked_attrs(true, false, *vars))
       end
 
-      # override attr_writer to track accessors for an TracksAttributes
+      # Override attr_writer to track accessors for an TracksAttributes.
+      # If the last argument may be a <tt>Hash</tt> of options where the
+      # options may be:
+      #
+      # * klass - the Class of the attribute to create when re-hydrating
+      #           the instance from a Hash/JSON/XML
+      #
       def attr_writer(*vars)
         # avoid tracking attributes that are added by the class_attribute
         # as these are class attributes and not instance attributes.
-        @tracked_attrs.concat vars.reject {|var| respond_to? var }
+        tracked_vars = vars.reject {|var| respond_to? var }
+        add_tracked_attrs(false, true, *tracked_vars)
+        vars.extract_options!
         super
       end
 
       # return an array of all of the attributes that are not in active record
       def accessors
-        @tracked_attrs ||= []
+        @tracked_attrs.keys ||= []
       end
 
+      # return the attribute information for the provided attribute
+      def attr_info_for(attribute_name)
+        @tracked_attrs[attribute_name.to_sym]
+      end
+      
+      # turn on ActiveModel:Validation validations
+      def enable_validations
+        include ActiveModel::Validations unless respond_to?(:_validators)
+      end
+      
+      private
+        def add_tracked_attrs(is_readable, is_writeable, *vars) #:nodoc:
+          attr_params = vars.extract_options!        
+          klass = attr_params[:klass]
+          vars.each do |var| 
+            @tracked_attrs[var] = AttrInfo.new(
+             :name  => var, 
+             :klass => klass, 
+             :is_readable   => is_readable,
+             :is_writeable  => is_writeable
+            )
+          end
+          vars
+        end
     end
 
     # Return the array of accessor symbols for instances of this
@@ -80,7 +165,7 @@ module TracksAttributes
 
     # Set all attributes with hash of symbols and their values and returns instance
     def all_attributes=(hash = {})
-      hash.each {|k, v| send("#{k.to_s}=", v) if respond_to? "#{k.to_s}=".to_sym}
+      hash.each { |k, v| set_attribute(k, v) }
       self
     end
 
@@ -122,7 +207,25 @@ module TracksAttributes
       self.all_attributes = hash
     end
 
+    private
+      def set_attribute(name, value) #:nodoc:
+        return unless respond_to? "#{name}=".to_sym 
+        
+        attr_info = self.class.attr_info_for name
+        klass     = attr_info && attr_info.klass
+        
+        if klass && klass.respond_to?(:create)
+          value = value.kind_of?(Array)? set_array_values(value, klass) : klass.create(value)
+        end
+        
+        send("#{name}=", value)
+      end
+      
+      def set_array_values(array, klass) #:nodoc:
+        array.map { |value| klass.create value }
+      end
   end
 end
 
-require 'tracks_attributes/railtie'
+require 'tracks_attributes/base'
+require 'tracks_attributes/railtie'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tracks-attributes
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-03 00:00:00.000000000 Z
+date: 2013-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -52,6 +52,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/tasks/tracks_attributes_tasks.rake
+- lib/tracks_attributes/attr_info.rb
+- lib/tracks_attributes/base.rb
 - lib/tracks_attributes/railtie.rb
 - lib/tracks_attributes/version.rb
 - lib/tracks_attributes.rb
@@ -84,4 +86,4 @@ specification_version: 3
 summary: TracksAttributes adds the ability to track ActiveRecord and Object level
   attributes.
 test_files: []
-has_rdoc: 
+has_rdoc: yard