delineate 0.6.0

data/lib/delineate/attribute_map/csv_serializer.rb

@@ -0,0 +1,133 @@
+require 'csv'
+
+module Delineate
+  module AttributeMap
+
+    # AttributeMap serializer that handles CSV as the external data format.
+    class CsvSerializer < MapSerializer
+
+      # Returns the record's mapped attributes as a CSV string. If
+      # you specify a truthy value for the :include_header option,
+      # the CSV header is output as the first line.
+      #
+      # See the description in +serializable_record+ for the order
+      # of the attributes.
+      def serialize(options = {})
+        opts = options[:include_header] ?
+          {:write_headers => true, :headers => serializable_header, :encoding => "UTF-8"} :
+          {:encoding => "UTF-8"}
+
+        opts = remove_serializer_class_options(options).merge(opts)
+        opts.delete(:include_header)
+
+        CSV.generate(opts) do |csv|
+          serializable_record.each {|r| csv << r}
+        end
+      end
+
+      # Returns the header row as a CSV string.
+      def serialize_header(options = {})
+        opts = {:encoding => "UTF-8"}.merge(remove_serializer_class_options(options))
+        CSV.generate_line(serializable_header, opts)
+      end
+
+      # Not implemented yet.
+      def serialize_in(csv_string, options = {})
+        raise "Serializing from CSV is not supported at this time. You can inherit a class from CsvSerializer to write a custom importer."
+      end
+
+      # Returns the record's mapped attributes in the serializer's "internal"
+      # format. For this class the representation is an array of one or more
+      # rows, one row for each item in teh record's has_many collections. Each
+      # row is an array of values ordered as follows:
+      #
+      #   1. All the record's mapped attributes in map order.
+      #   2. All one-to-one mapped association attributes in map order.
+      #   3. All one-to-many mapped association attributes in map order
+      #
+      # Do not specify any method parameters when calling +serializable_record+.
+      def serializable_record(prefix = [], top_level = true)
+        new_rows = []
+
+        prefix += serializable_attribute_names.map do |name|
+          @attribute_map.attribute_value(@record, name)
+        end
+
+        add_includes(:one_to_one) do |association, record, opts, nil_record|
+          assoc_map = association_attribute_map(association)
+          prefix, new_rows = self.class.new(record, assoc_map, opts).serializable_record(prefix, false)
+        end
+
+        add_includes(:one_to_many) do |association, records, opts, nil_record|
+          assoc_map = association_attribute_map(association)
+          records.each do |r|
+            p, next_rows = self.class.new(r, assoc_map, opts).serializable_record(prefix, false)
+            new_rows << (next_rows.empty? ? p : next_rows) unless nil_record
+          end
+        end
+
+        top_level ? (new_rows << prefix if new_rows.empty?; new_rows) : [prefix, new_rows]
+      end
+
+      # Returns the header row as an array of strings, one for each
+      # mapped attribute, including nested assoications. The items
+      # appear in the array in the same order as their corresponding
+      # attribute values.
+      def serializable_header(prefix = '')
+        returning(serializable_header = serializable_attribute_names) do
+          serializable_header.map! {|h| headerize(prefix + h.to_s)}
+
+          add_includes(:one_to_one) do |association, record, opts|
+            assoc_map = association_attribute_map(association)
+            assoc_prefix = prefix + association.to_s + '_'
+            serializable_header.concat self.class.new(record, assoc_map, opts).serializable_header(assoc_prefix)
+          end
+
+          add_includes(:one_to_many) do |association, records, opts|
+            assoc_map = association_attribute_map(association)
+            assoc_prefix = prefix + association.to_s.singularize + '_'
+            serializable_header.concat self.class.new(records.first, assoc_map, opts).serializable_header(assoc_prefix)
+          end
+        end
+      end
+
+      private
+
+        # The diff here is that if the associaton record(s) is empty, we have to generate
+        # a new empty record: @record.class.new.build_xxx or @record.class.new.xxx.build
+        def add_includes(assoc_type)
+          includes = @options.delete(:include)
+          assoc_includes, associations = serializable_association_names(includes)
+
+          for association in associations
+            model_assoc = @attribute_map.model_association(association)
+
+            case reflection(model_assoc).macro
+            when :has_many, :has_and_belongs_to_many
+              next if assoc_type == :one_to_one
+              records = @record.send(model_assoc).to_a
+              records = [@record.class.new.send(model_assoc).build] if (nil_record = records.empty?)
+            when :has_one, :belongs_to
+              next if assoc_type != :one_to_one
+              records = @record.send(model_assoc)
+              records = @record.class.new.send('build_'+model_assoc.to_s) if (nil_record = records.nil?)
+            end
+
+            yield(association, records, assoc_includes.is_a?(Hash) ? assoc_includes[association] : {}, nil_record)
+          end
+
+          @options[:include] = includes if includes
+        end
+
+        def headerize(attribute_name)
+          str = attribute_name.gsub(/_/, " ").gsub(/\b('?[a-z])/) { $1.capitalize }
+
+          words = str.split(' ')
+          str = words[0..-2].join(' ') if words[-2] == words[-1]
+          str
+        end
+
+    end
+
+  end
+end

data/lib/delineate/attribute_map/json_serializer.rb

@@ -0,0 +1,37 @@
+module Delineate
+  module AttributeMap
+
+    # AttributeMap serializer that handles JSON as the external data format.
+    class JsonSerializer < MapSerializer
+
+      # Returns the record's mapped attributes as a JSON string. The specified options
+      # are passed to the JSON.encode() function.
+      def serialize(options = {})
+        hash = super()
+
+        if options[:root] == true
+          hash = { @record.class.model_name.element.to_sym => hash }
+        elsif options[:root]
+          hash = { options[:root].to_sym => hash }
+        end
+        opts = remove_serializer_class_options(options)
+        opts.delete(:root)
+
+        hash.to_json(opts)
+      end
+
+      # Takes a record's attributes represented as a JSON string, and returns a
+      # hash suitable for direct assignment to the record's collection of attributes.
+      # For example:
+      #
+      #   s = ActiveRecord::AttributeMap::JsonSerializer.new(record, :api)
+      #   record.attributes = s.serialize_in(json_string)
+      #
+      def serialize_in(json_string, options = {})
+        super(ActiveSupport::JSON.decode(json_string), options)
+      end
+
+    end
+
+  end
+end

data/lib/delineate/attribute_map/map_serializer.rb

@@ -0,0 +1,170 @@
+module Delineate #:nodoc:
+  module AttributeMap
+
+    # The MapSerializer class serves as the base class for processing the
+    # reading and writing of ActiveRecord model attributes through an
+    # attribute map. Each serializer class supports its own external format
+    # for the input/output of the attributes. The format handled by MapSerializer
+    # is a hash.
+    class MapSerializer
+
+      # Creates a serializer for a single record.
+      #
+      # The +attribute_map+ parameter can be an AttributeMap instance or the
+      # name of the record's attribute map. The +options+ hash is used to
+      # filter which attributes and associations are to be serialized for
+      # output, and can have the following keys:
+      #
+      #   :include  Specifies which optional attributes and associations to output.
+      #   :only     Restricts the attributes and associations to only those specified.
+      #   :except   Processes attributes and associations except those specified.
+      #
+      # See the description for +mapped_attributes+ for more info about options.
+      #
+      def initialize(record, attribute_map, options = nil)
+        @record = record
+        attribute_map = record.send(:attribute_map, attribute_map) if attribute_map.is_a?(Symbol)
+        @attribute_map = attribute_map
+        @options = options ? options.dup : {}
+      end
+
+      # Returns the record's mapped attributes in the serializer's intrinsic format.
+      #
+      # For the MapSerializer class the attributes are returned as a hash,
+      # and the +options+ parameter is ignored.
+      def serialize(options = {})
+        @attribute_map.resolve! unless @attribute_map.resolved?
+        serializable_record
+      end
+
+      # Takes a record's attributes in the serializer's intrinsic format, and
+      # returns a hash suitable for direct assignment to the record's collection
+      # of attributes. For example:
+      #
+      #   s = ActiveRecord::AttributeMap::MapSerializer.new(record, :api)
+      #   record.attributes = s.serialize_in(attrs_hash)
+      #
+      def serialize_in(attributes, options = {})
+        @attribute_map.resolve! unless @attribute_map.resolved?
+        @attribute_map.map_attributes_for_write(attributes, options)
+      end
+
+      # Returns the record's mapped attributes in the serializer's "internal"
+      # format, usually this is a hash.
+      def serializable_record
+        returning(serializable_record = Hash.new) do
+          serializable_attribute_names.each do |name|
+            serializable_record[name] = @attribute_map.attribute_value(@record, name)
+          end
+
+          add_includes do |association, records, opts|
+            polymorphic = @attribute_map.associations[association][:options][:polymorphic]
+            assoc_map = association_attribute_map(association)
+
+            if records.is_a?(Enumerable)
+              serializable_record[association] = records.collect do |r|
+                assoc_map = attribute_map_for_record(r) if polymorphic
+                self.class.new(r, assoc_map, opts).serializable_record
+              end
+            else
+              assoc_map = attribute_map_for_record(records) if polymorphic
+              serializable_record[association] = self.class.new(records, assoc_map, opts).serializable_record
+            end
+          end
+        end
+      end
+
+      protected
+
+        # Returns the list of mapped attribute names that are to be output
+        # by applying the serializer's +:include+, +:only+, and +:except+
+        # options to the attribute map.
+        def serializable_attribute_names
+          includes = @options[:include] || []
+          includes = [] if includes.is_a?(Hash)
+          attribute_names = @attribute_map.serializable_attribute_names(Array(includes))
+
+          if @options[:only]
+            @options.delete(:except)
+            attribute_names & Array(@options[:only])
+          else
+            @options[:except] = Array(@options[:except])
+            attribute_names - @options[:except]
+          end
+        end
+
+        # Returns the list of mapped association names that are to be output
+        # by applying the serializer's +:include+ to the attribute map.
+        def serializable_association_names(includes)
+          assoc_includes = includes
+          if assoc_includes.is_a?(Array)
+            if (h = includes.detect {|i| i.is_a?(Hash)})
+              assoc_includes = h.dup
+              includes.each { |i| assoc_includes[i] = {} unless i.is_a?(Hash) }
+            end
+          end
+
+          include_has_options = assoc_includes.is_a?(Hash)
+          include_associations = include_has_options ? assoc_includes.keys : Array(assoc_includes)
+          associations = @attribute_map.serializable_association_names(include_associations)
+
+          if @options[:only]
+            @options.delete(:except)
+            associations = associations & Array(@options[:only])
+          else
+            @options[:except] = Array(@options[:except])
+            associations = associations - @options[:except]
+          end
+
+          [assoc_includes, associations]
+        end
+
+        # Helper for serializing nested models
+        def add_includes(&block)
+          includes = @options.delete(:include)
+          assoc_includes, associations = serializable_association_names(includes)
+
+          for association in associations
+            model_assoc = @attribute_map.model_association(association)
+
+            records = case reflection(model_assoc).macro
+            when :has_many, :has_and_belongs_to_many
+              @record.send(model_assoc).to_a
+            when :has_one, :belongs_to
+              @record.send(model_assoc)
+            end
+
+            yield(association, records, assoc_includes.is_a?(Hash) ? assoc_includes[association] : {}) if records
+          end
+
+          @options[:include] = includes if includes
+        end
+
+        # Returns an association's attribute map - argument is external name
+        def association_attribute_map(association)
+          @attribute_map.association_attribute_map(association)
+        end
+
+        # Returns the attribute map for the specified record - ensures it
+        # is resolved and valid.
+        def attribute_map_for_record(record)
+          @attribute_map.validate(record.attribute_map(@attribute_map.name), record.class.name)
+        end
+
+        # Gets association reflection
+        def reflection(model_assoc)
+          klass = @record.class
+          reflection = klass.reflect_on_association(model_assoc)
+          reflection || (klass.cti_base_class.reflect_on_association(model_assoc) if klass.is_cti_subclass?)
+        end
+
+        SERIALIZER_CLASS_OPTIONS = [:include, :only, :except, :context]
+
+        def remove_serializer_class_options(options)
+          options.reject {|k,v| SERIALIZER_CLASS_OPTIONS.include?(k)}
+        end
+
+    end
+
+  end
+end

data/lib/delineate/attribute_map/xml_serializer.rb

@@ -0,0 +1,45 @@
+module Delineate
+  module AttributeMap
+
+    # AttributeMap serializer that handles XML as the external data format.
+    class XmlSerializer < MapSerializer
+
+      # Returns the record's mapped attributes as XML. The specified options
+      # are passed to the XML builder. Some typical options are:
+      #
+      #   :root
+      #   :dasherize
+      #   :skip_types
+      #   :skip_instruct
+      #   :indent
+      #
+      def serialize(options = {})
+        hash = super()
+
+        if options[:root] == true
+          root_option = {:root => @record.class.model_name.element}
+        elsif options[:root]
+          root_option = {:root => options[:root]}
+        else
+          root_option = {}
+        end
+        opts = remove_serializer_class_options(options).merge(root_option)
+
+        hash.to_xml(opts)
+      end
+
+      # Takes a record's attributes represented in XML, and returns a hash
+      # suitable for direct assignment to the record's collection of attributes.
+      # For example:
+      #
+      #   s = Delineate::AttributeMap::XmlSerializer.new(record, :api)
+      #   record.attributes = s.serialize_in(xml_string)
+      #
+      def serialize_in(xml_string, options = {})
+        super(Hash.from_xml(xml_string), options)
+      end
+
+    end
+
+  end
+end

data/lib/delineate/map_attributes.rb

@@ -0,0 +1,201 @@
+require 'delineate/attribute_map/attribute_map'
+require 'delineate/attribute_map/map_serializer'
+require 'class_inheritable_attributes'
+
+module ActiveRecord
+
+  # Extend the ActiveRecord::Base class to include methods for defining and
+  # reading/writing the model API attributes.
+  class Base
+
+    # Collection of declared attribute maps for the model class
+    class_inheritable_accessor :attribute_maps
+    self.attribute_maps = {}
+
+    # The map_attributes method lets an ActiveRecord model class define a set
+    # of attributes that are to be exposed through the model's public interface.
+    # See the AttributeMap documentation for more information.
+    #
+    # The map_name parameter names the attribute map, and must be unique within
+    # a model class.
+    #
+    #   class Account < ActiveRecord::Base
+    #     map_attributes :api do
+    #       .
+    #       .
+    #     end
+    #
+    #     map_attributes :csv_export do
+    #       .
+    #       .
+    #     end
+    #   end
+    #
+    # ActiveRecord STI subclasses inherit the attribute map of the same name
+    # from their superclass. If you want to include additional subclass attributes,
+    # just invoke map_attributes in the subclass and define the extra attributes
+    # and associations. If the subclass wants to completely override/replace
+    # the superclass map, do:
+    #
+    #   map_attributes :api, :override => :replace do
+    #     .
+    #     .
+    #   end
+    #
+    # To access (read) a model instance's attributes via an attribute map,
+    # you invoke a method on the instance named <map-name>_attributes. For
+    # example:
+    #
+    #   attrs = post.api_attributes
+    #
+    # retrieves the attributes as specified in the Post model attribute
+    # map named :api. A hash of the API attributes is returned.
+    #
+    # An optional +options+ parameter lets you include attributes and
+    # associations that are defined as :optional in the attribute map.
+    # Following are some examples:
+    #
+    #   post.api_attributes(:include => :author)
+    #   post.api_attributes(:include => [:author, :comments])
+    #
+    # Include the balance attribute and also the description attribute in the
+    # :type association:
+    #
+    #   account.api_attributes(:include => [:balance, {:type => :description}])
+    #
+    # Another exmpale: in the :type association, include the optional name attribute,
+    # the desc attribute of the category association, and all the mapped attributes of
+    # the :type association named :assoc2.
+    #
+    #   account.api_attributes(:include => {:type => [:name, {:category => :desc}, :assoc2]})
+    #
+    # Other include forms:
+    #   :include => :attr1
+    #   :include => :assoc1
+    #   :include => [:attr1, :attr2, :assoc1]
+    #   :include => {:assoc1 => {}, :assoc2 => {:include => [:attr1, :attr2]}}
+    #   :include => [:attr1, :attr2, {:assoc1 => {:include => :assoc2}}, :assoc3]
+    #
+    # In addition to the :include option, you can specify:
+    #
+    #   :only     Restricts the attributes and associations to only those specified.
+    #   :except   Processes attributes and associations except those specified.
+    #
+    # To update/set a model instance's attributes via an attribute map,
+    # you invoke a setter method on the instance named <map_name>_attributes=.
+    # For example:
+    #
+    #   post.api_attributes = attr_hash
+    #
+    # The input hash contains name/value pairs, including those for nested
+    # models as defined as writeable in the attribute map. The input attribute
+    # values are mapped to the appropriate model attributes and associations.
+    #
+    # NOTE: Maps should pretty much be the last thing defined at the class level, but
+    # especially after the model class's associations and accepts_nested_attributes_for.
+    #
+    def self.map_attributes(map_name, options = {}, &blk)
+      map = Delineate::AttributeMap::AttributeMap.new(self.name, map_name, options)
+
+      # If this is a CTI subclass, init this map with its base class attributes and associations
+      if respond_to?(:is_cti_subclass) and is_cti_subclass? and options[:override] != :replace
+        base_class_map = cti_base_class.attribute_map(map_name)
+        raise "Base class for CTI subclass #{self.name} must specify attribute map #{map_name}" if base_class_map.nil?
+
+        base_class_map.attributes.each { |attr, opts| map.attribute(attr, opts.dup) }
+        base_class_map.associations.each do |name, assoc|
+          map.association(name, assoc[:options].merge({:attr_map => assoc[:attr_map].try(:dup)})) unless assoc[:klass_name] == self.name
+        end
+      end
+
+      # Parse the map specification DSL
+      map.instance_eval(&blk)
+
+      define_attribute_map_methods(map_name)      # define map accessor methods
+      attribute_maps[map_name] = map
+    end
+
+    def self.attribute_map(map_name)
+      attribute_maps.try(:fetch, map_name, nil)
+    end
+
+    def attribute_map(map_name)
+      self.class.attribute_maps[map_name]
+    end
+
+    # Returns the attributes as specified in the attribut map. The +format+ paramater
+    # can be one of the following: :hash, :json, :xml, :csv.
+    #
+    # The supported options hash keys are:
+    #
+    #   :include  Specifies which optional attributes and associations to output.
+    #   :only     Restricts the attributes and associations to only those specified.
+    #   :except   Processes attributes and associations except those specified.
+    #   :context  If this option is specified, then attribute readers and writers
+    #             defined as symbols will be executed as instance methods on the
+    #             specified context object.
+    #
+    def mapped_attributes(map_name, format = :hash, options = {})
+      map = validate_parameters(map_name, format)
+      @serializer_context = options[:context]
+
+      serializer_class(format).new(self, map, options).serialize(options)
+    end
+
+    # Sets the model object's attributes from the input hash. The hash contains
+    # name/value pairs, including those for nested models as defined as writeable
+    # in the attribute map. The input attribute names are mapped to the appropriate
+    # model attributes and associations.
+    #
+    def mapped_attributes=(map_name, attrs, format = :hash, options = {})
+      map = validate_parameters(map_name, format)
+      @serializer_context = options[:context]
+
+      self.attributes = serializer_class(format).new(self, map).serialize_in(attrs, options)
+    end
+    alias_method :set_mapped_attributes, :mapped_attributes=
+
+    private
+
+      # Defines the attribute map accessor methods:
+      #
+      #   def api_attributes([format = :hash,] options = {})    # returns the mapped attributes as a hash
+      #   def api_attributes=(attr_hash, options={})            # sets model attributes via the map
+      #
+      def self.define_attribute_map_methods(map_name)
+        class_eval do
+          define_method("#{map_name}_attributes") do |*args|
+            format = args.first && args.first.is_a?(Symbol) ? args.first : :hash
+            options = args.last.is_a?(Hash) ? args.last : {}
+            mapped_attributes(map_name, format, options)
+          end
+
+          define_method("#{map_name}_attributes=") do |attr_hash|
+            set_mapped_attributes(map_name, attr_hash, :hash)
+          end
+        end
+      end
+
+      def serializer_class(format)
+        if format == :hash
+          Delineate::AttributeMap::MapSerializer
+        else
+          "Delineate::AttributeMap::#{format.to_s.camelize}Serializer".constantize
+        end
+      end
+
+      def validate_parameters(map_name, format)
+        map = map_name
+        if map_name.is_a? Symbol
+          map = attribute_map(map_name)
+          raise ArgumentError, "Missing attribute map :#{map_name} for class #{self.class.name}" if map.nil?
+        end
+
+        raise ArgumentError, "The map parameter :#{map_name} for class #{self.class.name} is invalid" if !map.is_a?(Delineate::AttributeMap::AttributeMap)
+        raise ArgumentError, 'Invalid format parameter' unless [:hash, :csv, :xml, :json].include?(format)
+        map
+      end
+
+  end
+
+end