flat_map 0.0.3

data/lib/flat_map/base_mapper/attribute_methods.rb

@@ -0,0 +1,54 @@
+module FlatMap
+  # This module allows mappers to return and assign values via method calls
+  # which names correspond to names of mappings defined within the mapper.
+  #
+  # This methods are defined within anonymous module that will extend
+  # mapper on first usage of this methods.
+  #
+  # NOTE: :to_ary method is called internally by Ruby 1.9.3 when we call
+  # something like [mapper].flatten. And we DO want default behavior
+  # for handling this missing method.
+  module BaseMapper::AttributeMethods
+    # Lazily define reader and writer methods for all mappings available
+    # to the mapper, and extend +self+ with it.
+    def method_missing(name, *args, &block)
+      if name == :to_ary ||
+          @attribute_methods_defined ||
+          FlatMap::BaseMapper.protected_instance_methods.include?(name)
+        return super
+      end
+
+      mappings    = all_mappings
+      valid_names = mappings.map{ |_mapping|
+                      mapping_full_name = _mapping.full_name
+                      [ mapping_full_name,
+                        "#{mapping_full_name}=".to_sym ]
+                    }.flatten
+
+      return super unless valid_names.include?(name)
+
+      extend attribute_methods(mappings)
+      @attribute_methods_defined = true
+      send(name, *args, &block)
+    end
+
+    # Define anonymous module with reader and writer methods for
+    # all the +mappings+ being passed.
+    #
+    # @param [Array<FlatMap::Mapping>] mappings list of mappings
+    # @return [Module] module with method definitions
+    def attribute_methods(mappings)
+      Module.new do
+        mappings.each do |_mapping|
+          mapping_full_name = _mapping.full_name
+          define_method(mapping_full_name){ |*args| _mapping.read(*args) }
+
+          define_method("#{mapping_full_name}=") do |value|
+            _mapping.write(value)
+          end
+        end
+      end
+    end
+    private :attribute_methods
+  end
+end

data/lib/flat_map/base_mapper/factory.rb

@@ -0,0 +1,238 @@
+module FlatMap
+  # Mapper factory objects are used to store mounting and trait definitions
+  # and to instantiate and setup corresponding mapper objects thereafter.
+  # Factory objects are stored by mapper classes in opposite to actual
+  # mounted mappers that are stored by mapper objects themselves.
+  class BaseMapper::Factory
+    # Initializes factory with an identifier (name of a mounted mapper,
+    # or the actual class for a trait) and a set of options. Those args
+    # are used to create actual mapper object for the host mapper.
+    #
+    # @param [Symbol, Class] identifier name of a mapper or mapper class
+    #   itself
+    # @param [Hash] options
+    def initialize(identifier, options = {}, &block)
+      @identifier, @options, @extension = identifier, options, block
+    end
+
+    # Return +true+ if factory defines a trait.
+    #
+    # @return [Boolean]
+    def traited?
+      @identifier.is_a?(Class)
+    end
+
+    # Return the name of the mapper being defined by the factory.
+    # Return +nil+ for the traited factory.
+    #
+    # @return [Symbol, nil]
+    def name
+      traited? ? nil : @identifier
+    end
+
+    # Return the trait name if the factory defines a trait.
+    def trait_name
+      @options[:trait_name] if traited?
+    end
+
+    # Return the list of traits that should be applied for a mapper being
+    # mounted on a host mapper.
+    #
+    # @return [Array<Symbol>] list of traits
+    def traits
+      Array(@options[:traits]).compact
+    end
+
+    # Return the anonymous trait class if the factory defines a trait.
+    # Fetch and return the class of a mapper defined by a symbol.
+    #
+    # @return [Class] ancestor of {FlatMap::BaseMapper}
+    def mapper_class
+      return @identifier if traited?
+
+      class_name = @options[:mapper_class_name] || "#{name.to_s.camelize}Mapper"
+      class_name.constantize
+    end
+
+    # Return +true+ if factory should create targeted mapper.
+    #
+    # @return [Boolean]
+    def targeted_mount?
+      mapper_class < Mapper
+    end
+
+    # Fetch the target for the mapper being created based on target of a host mapper.
+    #
+    # @param [FlatMap::BaseMapper] mapper Host mapper
+    # @return [Object] target for new mapper
+    def fetch_target_from(mapper)
+      return explicit_target!(mapper) if mapper.is_a?(EmptyMapper) && targeted_mount?
+
+      owner_target = mapper.target
+
+      return owner_target if traited?
+
+      explicit_target(owner_target)         ||
+      target_from_association(owner_target) ||
+      target_from_name(owner_target)
+    end
+
+    # When creating mappers mounted on top of EmptyMapper, target cannot be implicitly
+    # fetched from it and should be specified explicitly.
+    #
+    # @param [FlatMap::EmptyMapper] mapper Host empty mapper
+    # @return [Object] target for new mapper
+    def explicit_target!(mapper)
+      target = @options[:target]
+
+      if target.present?
+        case target
+        when Proc   then target.call
+        when Symbol then mapper.send(target)
+        else target
+        end
+      else
+        raise Mapper::Targeting::NoTargetError.new(mapper_class)
+      end
+    end
+
+    # Try to use explicit target definition passed in options to fetch a
+    # target. If this value is a +Proc+, will call it with owner target as
+    # argument.
+    #
+    # @param [Object] owner_target
+    # @return [Object, nil] target for new mapper.
+    def explicit_target(owner_target)
+      if @options.key?(:target)
+        target = @options[:target]
+        if target.is_a? Proc
+          target.call(owner_target)
+        else
+          target
+        end
+      end
+    end
+
+    # Try to fetch the target for a new mapper being mounted, based on
+    # correspondence of the mounting name and presence of the association
+    # with a similar name in the host mapper.
+    #
+    # For example:
+    #   class Foo < ActiveRecord::Base
+    #     has_one :baz
+    #     has_many :bars
+    #   end
+    #
+    #   class FooMapper < FlatMap::Mapper
+    #     # target of this mapper is the instance of Foo. Lets reference it as 'foo'
+    #     mount :baz # This will look for BazMapper, and will try to fetch a target for
+    #                # it based on :has_one association, i.e. foo.baz || foo.build_baz
+    #
+    #     mount :bar # This will look for BarMapper, and will try to fetch a target for
+    #                # it based on :has_many association, i.e. foo.bars.build
+    #   end
+    def target_from_association(owner_target)
+      return unless owner_target.kind_of?(ActiveRecord::Base)
+
+      reflection = reflection_from_target(owner_target)
+      return unless reflection.present?
+
+      reflection_macro = reflection.macro
+      case
+      when reflection_macro == :has_one && reflection.options[:is_current]
+        owner_target.send("effective_#{name}")
+      when reflection_macro == :has_one || reflection_macro == :belongs_to
+        owner_target.send(name) || owner_target.send("build_#{name}")
+      when reflection_macro == :has_many
+        owner_target.association(reflection.name).build
+      else # nil
+      end
+    end
+
+    # Try to retreive an association reflection that has a name corresponding
+    # to the one of +self+
+    #
+    # @param [ActiveRecord::Base] target
+    # @return [ActiveRecord::Reflection::AssociationReflection, nil]
+    def reflection_from_target(target)
+      return unless name.present? && target.is_a?(ActiveRecord::Base)
+      target_class = target.class
+      reflection   = target_class.reflect_on_association(name)
+      reflection  || target_class.reflect_on_association(name.to_s.pluralize.to_sym)
+    end
+
+    # Send the name of the mounting to the target of the host mapper, and use
+    # return value as a target for a mapper being created.
+    #
+    # @return [Object]
+    def target_from_name(target)
+      target.send(name)
+    end
+
+    # Return order relative to target of the passed +mapper+ in which mapper to
+    # be created should be saved. In particular, targets of <tt>:belongs_to</tt>
+    # associations should be saved before target of +mapper+ is saved.
+    #
+    # @param [FlatMap::BaseMapper] mapper
+    # @return [Symbol]
+    def fetch_save_order(mapper)
+      return :after if mapper.is_a?(EmptyMapper)
+
+      reflection = reflection_from_target(mapper.target)
+      return unless reflection.present?
+      reflection.macro == :belongs_to ? :before : :after
+    end
+
+    # Create a new mapper object for mounting. If the factory is traited,
+    # the new mapper is a part of a host mapper, and is 'owned' by it.
+    # Otherwise, assign the name of the factory to it to be able to find it
+    # later on.
+    #
+    # @param [FlatMap::BaseMapper] mapper Host mapper
+    # @param [*Symbol] owner_traits List of traits to be applied to a newly created mapper
+    def create(mapper, *owner_traits)
+      save_order = @options[:save] || fetch_save_order(mapper) || :after
+      all_traits = (traits + owner_traits).uniq
+
+      new_one =
+        if targeted_mount? then
+          mapper_class.new(fetch_target_from(mapper), *all_traits, &@extension)
+        else
+          mapper_class.new(*all_traits, &@extension)
+        end
+
+      if traited?
+        new_one.owner = mapper
+      else
+        new_one.host       = mapper
+        new_one.name       = @identifier
+        new_one.save_order = save_order
+
+        if (suffix = @options[:suffix] || mapper.suffix).present?
+          new_one.suffix = suffix
+          new_one.name   = :"#{@identifier}_#{suffix}"
+        else
+          new_one.name = @identifier
+        end
+      end
+      new_one
+    end
+
+    # Return +true+ if the factory is required to be able to apply a trait
+    # for the host mapper.
+    # For example, it is required if its name is listed in +traits+.
+    # It is also required if it has nested traits with names listed in +traits+.
+    #
+    # @param [Array<Symbol>] traits list of traits
+    # @return [Boolean]
+    def required_for_any_trait?(traits)
+      return true unless traited?
+
+      traits.include?(trait_name) ||
+        mapper_class.mountings.any?{ |factory|
+          factory.traited? &&
+          factory.required_for_any_trait?(traits)
+        }
+    end
+  end
+end

data/lib/flat_map/base_mapper/mapping.rb

@@ -0,0 +1,123 @@
+module FlatMap
+  # This module hosts all definitions required to define and use mapping
+  # functionality within mapper classes. This includes mapping definition
+  # methods and basic reading and writing methods.
+  module BaseMapper::Mapping
+    extend ActiveSupport::Concern
+
+    # Mapping class macros
+    module ClassMethods
+      # Mapping-modifier options to distinguish options from mappings
+      # themselves:
+      MAPPING_OPTIONS = [:reader, :writer, :format, :multiparam].freeze
+
+      # Define single or multiple mappings at a time. Usually, a Hash
+      # is passed in a form !{mapping_name => target_attribute}. All keys
+      # that are listed under {MAPPING_OPTIONS} will be extracted and used
+      # as modifiers for new mappings.
+      #
+      # Also, mapping names may be listed as an array preceding the hash.
+      # In that case, its elements are treated as !{mapping_name => mapping_name}
+      # mapping elements.
+      #
+      # Example:
+      #   map :brand, :account_source => :source, :format => :enum
+      #   # is equivalent to:
+      #   map :brand => :brand, :format => :enum
+      #   map :account_source => :source, :format => :enum
+      def map(*args)
+        mapping_options     = args.extract_options!
+        mappings            = mapping_options.slice!(*MAPPING_OPTIONS)
+        mappings_from_array = args.zip(args).flatten
+        mappings.merge!(Hash[*mappings_from_array]) unless mappings_from_array.empty?
+
+        define_mappings(mappings, mapping_options)
+      end
+
+      # Define a set of +mappings+, passed as a {Hash} with +options+ as modifiers.
+      # Eventually, adds a mapping factories to list of class mappings. Those
+      # factory objects are used to create actual mappings for specific mapper
+      # object.
+      #
+      # @param [Hash] mappings
+      # @param [Hash] options
+      # @return [Array<FlatMap::Mapping::Factory>] list of mappings
+      def define_mappings(mappings, options)
+        mappings.each do |name, target_attribute|
+          self.mappings << FlatMap::Mapping::Factory.new(name, target_attribute, options)
+        end
+      end
+      private :define_mappings
+
+      # List of class mappings (mapping factories).
+      #
+      # @return [Array<FlatMap::Mapping::Factory>]
+      def mappings
+        @mappings ||= []
+      end
+
+      # Writer for mappings.
+      def mappings=(val)
+        @mappings = val
+      end
+    end
+
+    # Send passed +params+ +write_from_params+ method of each
+    # of the mappings of +self+.
+    #
+    # Overloaded in {BaseMapper::Mounting}.
+    #
+    # @param [Hash] params
+    # @return [Hash] params
+    def write(params)
+      mappings.each do |mapping|
+        mapping.write_from_params(params)
+      end
+      params
+    end
+
+    # Send +read_as_params+ method to all mappings associated with
+    # self. And consolidate results in a single hash.
+    #
+    # @return [Hash] set of read values
+    def read
+      mappings.inject({}) do |params, mapping|
+        params.merge(mapping.read_as_params)
+      end
+    end
+
+    # Retrieve mapping value via its name, which might differ from its
+    # full_name, if suffix was used.
+    #
+    # @param [Symbol] name
+    def [](name)
+      mapping(name).try(:read)
+    end
+
+    # Write value to mapping specified by name, which might differ from its
+    # full_name, if suffix was used.
+    #
+    # @param [Symbol] name
+    # @param [Object] value
+    def []=(name, value)
+      mapping(name).try(:write, value)
+    end
+
+    # Lookup mapping by its name, which might differ from its
+    # full_name, if suffix was used.
+    #
+    # @param [Symbol] name
+    # @return [FlatMap::Mapping]
+    def mapping(name)
+      mappings.find{ |_mapping| _mapping.name == name }
+    end
+
+    # Return a list of mappings associated to +self+.
+    #
+    # @return [FlatMap::Mapping]
+    def mappings
+      @mappings ||= self.class.mappings.map{ |factory| factory.create(self) }
+    end
+    private :mappings
+  end
+end

data/lib/flat_map/base_mapper/mounting.rb

@@ -0,0 +1,168 @@
+module FlatMap
+  # This module hosts definitions required for mounting functionality
+  # of the mappers. This includes mounting definition methods, overloaded
+  # +read+ and +write+ methods to make them aware of mounted mappers and
+  # other methods.
+  #
+  # Also, the +method_missing+ method is defined here to delegate the missing
+  # method to the very first mounted mapper that responds to it.
+  module BaseMapper::Mounting
+    extend ActiveSupport::Concern
+
+    included do
+      attr_accessor :save_order
+    end
+
+    # Mounting class macros.
+    module ClassMethods
+      # Add a mounting factory to a list of factories of a class
+      # These factories are used to create actual mounted objects,
+      # which are mappers themselves, associated to a particular
+      # mapper.
+      #
+      # @param [*Object] args
+      # @return [Array<FlatMap::BaseMapper::Factory>]
+      def mount(*args, &block)
+        mountings << FlatMap::BaseMapper::Factory.new(*args, &block)
+      end
+
+      # List of mountings (factories) of a class.
+      #
+      # @return [Array<FlatMap::BaseMapper>]
+      def mountings
+        @mountings ||= []
+      end
+
+      # Writer for @mountings.
+      def mountings=(val)
+        @mountings = val
+      end
+    end
+
+    # Extend original {Mapping#read} method to take
+    # into account mountings of mounted mappers.
+    #
+    # @return [Hash] read values
+    def read
+      mountings.inject(super) do |result, mapper|
+        result.merge(mapper.read)
+      end
+    end
+
+    # Extend original {Mapping#write} method to pass
+    # +params+ to mounted mappers.
+    #
+    # Overridden in {Persistence}. Left here for consistency.
+    #
+    # @param [Hash] params
+    # @return [Hash] params
+    def write(params)
+      super
+
+      mountings.each do |mapper|
+        mapper.write(params)
+      end
+
+      params
+    end
+
+    # Return list of mappings to be saved before saving target of +self+
+    #
+    # @return [Array<FlatMap::BaseMapper>]
+    def before_save_mountings
+      nearest_mountings.select{ |mount| mount.save_order == :before }
+    end
+
+    # Return list of mappings to be saved after target of +self+ was saved
+    #
+    # @return [Array<FlatMap::BaseMapper>]
+    def after_save_mountings
+      nearest_mountings.reject{ |mount| mount.save_order == :before }
+    end
+
+    # Return all mountings that are mouted on +self+ directly or through
+    # traits.
+    #
+    # @return [Array<FlatMap::BaseMapper>]
+    def nearest_mountings
+      mountings.map{ |mount| mount.owned? ? mount.nearest_mountings : mount }.flatten
+    end
+
+    # Return a list of all mountings (mapper objects) associated with +self+.
+    #
+    # Overridden in {Traits}.
+    #
+    # @return [Array<FlatMap::BaseMapper>]
+    def mountings
+      @mountings ||= self.class.mountings.map{ |factory| factory.create(self) }
+    end
+
+    # Return a mapping with the name that corresponds to passed +mounting_name+,
+    # if it exists.
+    #
+    # @return [FlatMap::Mapping, nil]
+    def mounting(mounting_name, is_deep = true)
+      list = is_deep ? all_mountings : mountings
+      list.find{ |mount| mount.name == mounting_name }
+    end
+
+    # Return a list of all mounted mappers. If +self+ is a trait, return a
+    # list of all mountings of the owner. This will allow separate traits
+    # to share methods via method_missing pattern.
+    #
+    # @return [Array<FlatMap::BaseMapper>] mounted mappers (including traits)
+    def all_mountings
+      return all_nested_mountings.unshift(self) unless owned?
+      owner.all_mountings
+    end
+    protected :all_mountings
+
+    # Return a list of mountings that are accessible by a named mapper.
+    #
+    # @return [Array<FlatMap::BaseMapper>]
+    def all_nested_mountings
+      mountings.dup.concat(mountings.map{ |mount| mount.send(:all_nested_mountings) }).flatten
+    end
+    protected :all_nested_mountings
+
+    # Return a list of all mappings, i.e. mappings associated to +self+,
+    # plus mappings of all deeply mounted mappers. If +self+ is the owner,
+    # that means it is a part (a trait) of a host mapper. That means that all
+    # mappings of it actually correspond to all mappings of a host mapper.
+    # This allows to define things like validation in a trait where access
+    # to top-level mappings is required.
+    #
+    # @return [Array<FlatMap::Mapping>]
+    def all_mappings
+      return all_nested_mappings unless owned?
+      owner.all_mappings
+    end
+    protected :all_mappings
+
+    # Return a list of all mappings, i.e. mappings that associated to +self+
+    # plus mappings of all deeply mounted mappers.
+    #
+    # @return [Array<FlatMap::Mapping>]
+    def all_nested_mappings
+      (mappings + mountings.map{ |mount| mount.send(:all_nested_mappings) }).flatten
+    end
+    protected :all_nested_mappings
+
+    # Delegate missing method to any mounted mapping that respond to it,
+    # unless those methods are protected methods of FlatMap::BaseMapper.
+    #
+    # NOTE: :to_ary method is called internally by Ruby 1.9.3 when we call
+    # something like [mapper].flatten. And we DO want default behavior
+    # for handling this missing method.
+    def method_missing(name, *args, &block)
+      return super if name == :to_ary ||
+                      FlatMap::BaseMapper.protected_instance_methods.include?(name)
+
+      return self[name] if mapping(name).present?
+
+      mount = all_mountings.find{ |_mount| _mount.respond_to?(name) }
+      return super if mount.nil?
+      mount.send(name, *args, &block)
+    end
+  end
+end