seedable 0.0.1

data/lib/seedable.rb

@@ -0,0 +1,19 @@
+# encoding: UTF-8
+
+require "seedable/version"
+require "seedable/importer"
+require "seedable/exporter"
+require "seedable/helpers"
+require "seedable/core_ext"
+require "seedable/object_tracker"
+
+module Seedable # :nodoc:
+  include Seedable::Importer
+
+  extend ActiveSupport::Concern 
+
+  included do
+    include Seedable::Importer
+    include Seedable::Exporter
+  end
+end

data/lib/seedable/core_ext.rb

@@ -0,0 +1,66 @@
+# encoding: UTF-8
+
+module Seedable # :nodoc:
+  module CoreExt # :nodoc:
+    module Array # :nodoc:
+      extend ActiveSupport::Concern
+
+      module InstanceMethods # :nodoc:
+
+        # Serialize an array of heterogeneous objects.
+        #
+        def as_seedable
+          map { |o| o.as_seedable }
+        end
+
+        # Serialize an array of heterogeneous objects and output as
+        # JSON.
+        #
+        def to_seedable
+          as_seedable.to_json
+        end
+
+      end
+    end
+
+    module Serialization # :nodoc:
+      extend ActiveSupport::Concern
+
+      included do
+        alias_method_chain :serializable_hash, :object_tracker
+      end
+
+      # Use thread-local storage to carry the object tracker through the
+      # association traversal.
+      #
+      module InstanceMethods # :nodoc:
+
+        # Extend serializable_hash functionality by calling out to the
+        # object tracker.
+        #
+        def serializable_hash_with_object_tracker(options = {})
+          unless object_tracker = Thread.current[:object_tracker]
+            object_tracker                  = ObjectTracker.new
+            clean_up                        = true
+            Thread.current[:object_tracker] = object_tracker
+          end
+
+          if object_tracker.contains?(self)
+            return_value = {}
+          else
+            object_tracker.add(self)
+            return_value = serializable_hash_without_object_tracker(options)
+          end
+         
+          Thread.current[:object_tracker] = nil if clean_up
+
+          return_value
+        end
+      end
+    end
+  end
+end
+
+Array.send :include, Seedable::CoreExt::Array
+
+ActiveRecord::Base.send :include, Seedable::CoreExt::Serialization

data/lib/seedable/exporter.rb

@@ -0,0 +1,163 @@
+# encoding: UTF-8
+
+module Seedable # :nodoc:
+  module Exporter # :nodoc:
+    extend ActiveSupport::Concern
+
+    # Extensions to all ActiveRecord classes to enable this class for
+    # import and export of data.
+    #
+    # Use +acts_as_seedable+ here to enable your classes to use this
+    # functionality.
+    #
+    # Use +from_seedable+ and +to_seedable+ here to perform the
+    # serialization and deserialization.
+    #
+    module ClassMethods
+
+      # Enable seedable export and import for the including class.
+      #
+      # ==== Options
+      #
+      # * +filter_attributes+ - Attributes to filter from the export.
+      # * +include_associations+ - Associations that should be traversed during export.
+      #
+      # ==== Examples
+      #
+      #   class Garage < ActiveRecord::Base 
+      #     acts_as_seedable :include_associations => [:cars]
+      #   end
+      #
+      def seedable(options = {})
+        cattr_accessor :filterable_attributes
+        cattr_accessor :includable_associations
+
+        if options[:filter_attributes]
+          self.send(:filter_attributes, options.delete(:filter_attributes))
+        end
+
+        if options[:include_associations]
+          self.send(:include_associations, options.delete(:include_associations))
+        else
+          self.send(:include_associations, Helpers.associations_for(self))
+        end
+      end
+
+      # Return seedable status
+      #
+      def seedable?
+        self.respond_to?(:filterable_attributes) && self.respond_to?(:includable_associations)
+      end
+
+      # Sets which attributes should be fitlered from the
+      # serialization of this object.
+      #
+      # ==== Parameters
+      #
+      # * +attributes+ - Array of symbols representing attributes.
+      #
+      # ==== Examples
+      #
+      #   Garage.filter_attributes([:id, :name])
+      #
+      def filter_attributes(attributes)
+        self.send(:filterable_attributes=, attributes)
+      end
+
+      # Sets which associations should be traversed when performing
+      # serialization.
+      #
+      # ==== Parameters
+      #
+      # * +associations+ - Array of symbols representing associations.
+      #
+      # ==== Examples
+      #
+      #   Garage.include_associations([:cars])
+      #
+      #   Car.include_associations([:garage, :drivers])
+      #
+      def include_associations(associations)
+        self.send(:includable_associations=, associations)
+
+        unless Rails.env.production?
+          associations.each do |association|
+            self.accepts_nested_attributes_for association
+          end
+        end
+      end
+
+      # Create object from attributes without a root node, since it's
+      # assumed to be the type this method is being called on.
+      #
+      # ==== Parameters
+      #
+      # * +attributes+ - Hash of attributes, without a root node.
+      #
+      # ==== Examples
+      #
+      #   Garage.from_seedable_attributes({ :id => '1', :name => 'Name' })
+      #
+      def from_seedable_attributes(attributes) # :nodoc:
+        object = self.new
+
+        # Handling for rails-3.2.x vs. rails-3.0.x changes.
+        #
+        if object.respond_to?(:assign_attributes)
+          object.assign_attributes(
+            Helpers.convert_to_nested_attributes(self, attributes), 
+            :without_protection => true
+          )
+        else
+          object.send(
+            :attributes=,
+            Helpers.convert_to_nested_attributes(self, attributes), 
+            false
+          )
+        end
+
+        object.save!(:validate => false)
+        object
+      end
+
+    end
+
+    # Extensions to all ActiveRecord classes to enable this class for
+    # import and export of data.
+    #
+    # Use +acts_as_seedable+ here to enable your classes to use this
+    # functionality.
+    #
+    # Use +from_seedable+ and +to_seedable+ here to perform the
+    # serialization and deserialization.
+    #
+    module InstanceMethods
+      
+      # Returns hash of objects attributes and all included associations
+      # attributes.
+      # 
+      # ==== Examples 
+      #
+      #   json = @garage.as_seedable.to_json
+      #
+      def as_seedable
+        includable = Helpers.traverse_includable_associations_from_instance(self)
+        exceptions = Helpers.filterable_attributes(self)
+
+        self.as_json(:include => includable, :except => exceptions)
+      end
+
+      # Performs render of as_seedable content into properly formatted
+      # JSON.
+      #
+      # ==== Examples 
+      #
+      #   json = @garage.to_seedable
+      #
+      def to_seedable
+        as_seedable.to_json
+      end
+
+    end
+  end
+end

data/lib/seedable/helpers.rb

@@ -0,0 +1,144 @@
+# encoding: UTF-8
+
+module Seedable # :nodoc:
+  module Helpers # :nodoc:
+
+    # Convert a string or symbol to a class in the object space.
+    #
+    def self.to_class(string)
+      string.to_s.classify.constantize
+    end
+
+    # Parse a seedable object returning a hash.
+    #
+    def self.parse_seedable(json)
+      JSON.parse(json)
+    end
+
+    # Convert hash root node to class, and return attributes.
+    #
+    def self.to_class_and_attributes(hash)
+      node       = hash.keys.first
+      attributes = hash.delete(node)
+      klass      = Helpers.to_class(node)
+
+      [klass, attributes]
+    end
+
+    # Traverse all associations starting from an instance of a
+    # particular class.
+    #
+    def self.traverse_includable_associations_from_instance(klass)
+      traverse_includable_associations(klass.class, klass.class)
+    end
+
+    # Traverse all associations starting from a particular class.
+    #
+    def self.traverse_includable_associations(klass, ancestor_klass)
+      if klass.respond_to?(:includable_associations) 
+        klass.includable_associations.inject({}) do |associations, association|
+          descendent_klass = Helpers.to_class(association)
+          unless descendent_klass == ancestor_klass || !descendent_klass.seedable?
+            associations[association] = { 
+              :include => traverse_includable_associations(Helpers.to_class(association), klass),
+              :except  => filterable_attributes(Helpers.to_class(association))
+            }
+          end
+          associations
+        end
+      else 
+        {}
+      end
+    end
+
+    # Filterable attributes for a particular class.
+    #
+    def self.filterable_attributes(klass)
+      if klass.respond_to?(:filterable_attributes) 
+        klass.filterable_attributes
+      else
+        []
+      end
+    end
+
+    # Valid traversable association types.
+    #
+    def self.valid_association_types
+      [:has_many, :has_one, :belongs_to]
+    end
+
+    # Determine if a particular association macro is valid.
+    #
+    def self.valid_associations_include?(macro)
+      valid_association_types.include?(macro)
+    end
+
+    # Return all associations for a particular class.
+    #
+    def self.associations_for(klass)
+      klass.reflections.map do |reflection| 
+        valid_associations_include?(reflection.last.macro) ? reflection.first : nil
+      end.compact
+    end
+
+    # Returns true of a particular association is valid for a particular
+    # class.
+    #
+    def self.is_key_association_for_class?(klass, key)
+      klass.reflections.any? do |reflection| 
+        valid_associations_include?(reflection.last.macro) && reflection.first == key.to_sym
+      end
+    end
+
+    # Return all attributes in a hash, without the root node, if
+    # present.
+    #
+    def self.attributes_without_root(attributes, root) 
+      attributes.delete(root)
+    end
+
+    # Return the name of the nested association accessor for a
+    # particular association.
+    #
+    def self.nested_attributes_key_for(key)
+      "#{key}_attributes"
+    end
+
+    # Return a particular reflection on an object or class.
+    #
+    def self.return_reflection(klass, association) 
+      if klass.respond_to?(:reflect_on_association) 
+        klass.reflect_on_association(association)
+      else 
+        klass.class.reflect_on_association(association)
+      end
+    end
+
+    # Return the proper active_record reflection type for a nested
+    # association.
+    #
+    def self.reflection_type(klass, association)
+      return_reflection(klass, association).collection? ? :collection : :one_to_one
+    end
+
+    # Convert a hash of nested model attributes to a valid hash to be
+    # passed to assign_attributes by substituting association name for
+    # the appropriate association accessors.
+    #
+    def self.convert_to_nested_attributes(klass, node_attributes) 
+      node_attributes.keys.inject(node_attributes) do |attributes, key|
+        if is_key_association_for_class?(klass, key)
+          sub_attributes = attributes_without_root(attributes, key)
+
+          attributes[nested_attributes_key_for(key)] = sub_attributes.is_a?(Enumerable) ?
+            sub_attributes.map do |sub_attribute| 
+              convert_to_nested_attributes(to_class(key), sub_attribute)
+            end :
+            convert_to_nested_attributes(to_class(key), sub_attributes)
+        end
+        attributes
+      end
+    end
+  end
+end
+

data/lib/seedable/importer.rb

@@ -0,0 +1,55 @@
+# encoding: UTF-8
+
+module Seedable # :nodoc:
+  module Importer # :nodoc: 
+    extend ActiveSupport::Concern
+
+    # Seedable methods for loading serialized objects of unknown or
+    # disperse types into objects.
+    #
+    # Use +from_seedable+ here to load arrays of one or multiple types,
+    # or when you do not know what type of object the JSON represents to
+    # have it return the appropriate object.
+    #
+    module ClassMethods
+
+      # Takes JSON and builds objects from it.  Returns either the
+      # object, or array of objects depending on input.
+      #
+      # ==== Parameters
+      #
+      # * +json+ - A block of JSON.
+      # 
+      # ==== Examples
+      #
+      #   array_of_objects = Seedable.from_seedable(json_containing_array_of_hashes)
+      #   object = Seedable.from_seedable(json_for_one_object)
+      #
+      def from_seedable(json)
+        objects = Helpers.parse_seedable(json)
+
+        if Array === objects
+          objects.map do |object| 
+            objects_from_serialized_hash(object)
+          end
+        else
+          objects_from_serialized_hash(objects)
+        end
+      end
+
+      # Convert a hash's root node to a class, and return the remainder
+      # of the hash as attributes.
+      #
+      # ==== Parameters
+      #
+      # * +hash+ - Hash with one root note reflecting a class.
+      #
+      def objects_from_serialized_hash(hash) # :nodoc:
+        klass, attributes = Helpers.to_class_and_attributes(hash)
+        klass.from_seedable_attributes(attributes)
+      end
+      private :objects_from_serialized_hash
+
+    end
+  end
+end