HornsAndHooves-flat_map 0.2.0

data/lib/flat_map/open_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 OpenMapper::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 {OpenMapper::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/open_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 OpenMapper::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::OpenMapper::Factory>]
+      def mount(*args, &block)
+        mountings << FlatMap::OpenMapper::Factory.new(*args, &block)
+      end
+
+      # List of mountings (factories) of a class.
+      #
+      # @return [Array<FlatMap::OpenMapper>]
+      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::OpenMapper>]
+    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::OpenMapper>]
+    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::OpenMapper>]
+    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}. Left here for consistency.
+    #
+    # @return [Array<FlatMap::OpenMapper>]
+    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::OpenMapper>] 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::OpenMapper>]
+    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::OpenMapper.
+    #
+    # 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 ||
+                              self.class.protected_instance_methods.include?(name)
+
+      return self[name] if mapping(name).present?
+
+      mounting = all_mountings.find{ |mount| mount.respond_to?(name) }
+      return super if mounting.nil?
+      mounting.send(name, *args, &block)
+    end
+  end
+end

data/lib/flat_map/open_mapper/persistence.rb

@@ -0,0 +1,178 @@
+module FlatMap
+  # This module provides some integration between mapper and its target,
+  # which is usually an ActiveRecord model, as well as some integration
+  # between mapper and Rails forms.
+  #
+  # In particular, validation and save methods are defined here. And
+  # the <tt>save</tt> method itself is defined as a callback. Also, Rails
+  # multiparam attributes extraction is defined within this module.
+  module OpenMapper::Persistence
+    extend ActiveSupport::Concern
+
+    included do
+      define_callbacks :save
+    end
+
+    # ModelMethods class macros
+    module ClassMethods
+      # Create a new mapper object wrapped around new instance of its
+      # +target_class+, with a list of passed +traits+ applied to it.
+      #
+      # @param [*Symbol] traits
+      # @return [FlatMap::OpenMapper] mapper
+      def build(*traits, &block)
+        new(target_class.new, *traits, &block)
+      end
+
+      # Default target class for OpenMapper is OpenStruct.
+      #
+      # @return [Class] class
+      def target_class
+        OpenStruct
+      end
+    end
+
+    # Write a passed set of +params+. Then try to save the model if +self+
+    # passes validation. Saving is performed in a transaction.
+    #
+    # @param [Hash] params
+    # @return [Boolean]
+    def apply(params)
+      write(params)
+      valid? && save
+    end
+
+    # Extract the multiparam values from the passed +params+. Then use the
+    # resulting hash to assign values to the target. Assignment is performed
+    # by sending writer methods to +self+ that correspond to keys in the
+    # resulting +params+ hash.
+    #
+    # @param [Hash] params
+    # @return [Hash] params
+    def write(params)
+      extract_multiparams!(params)
+
+      params.each do |name, value|
+        self.send("#{name}=", value)
+      end
+    end
+
+    # Try to save the target and send a +save+ method to all mounted mappers.
+    #
+    # The order in which mappings are saved is important, since we save
+    # records with :validate => false option. Since Rails will perform
+    # auto-saving on associations (and it in its turn will try to save associated
+    # record with :validate => true option. To be more precise, with
+    # :validate => !autosave option, where autosave corresponds to that option
+    # of reflection, which is usually not specified, i.e. nil), we might come to
+    # a situation of saving a record with nil foreign key for belongs_to association,
+    # which will raise exception. Thus, we want to explicitly save records in
+    # order which will allow them to be saved.
+    # Return +false+ if that chain of +save+ calls returns +true+ on any of
+    # its elements. Return +true+ otherwise.
+    #
+    # Saving is performed as a callback.
+    #
+    # @return [Boolean]
+    def save
+      before_res = save_mountings(before_save_mountings)
+      target_res = self_mountings.map{ |mount| mount.shallow_save }.all?
+      after_res  = save_mountings(after_save_mountings)
+
+      before_res && target_res && after_res
+    end
+
+    # Return +true+ since OpenStruct is always 'saved'.
+    #
+    # @return [true]
+    def save_target
+      true
+    end
+
+    # Perform target save with callbacks call
+    #
+    # @return [Boolean]
+    def shallow_save
+      run_callbacks(:save){ save_target }
+    end
+
+    # Return +true+ if target was updated.
+    #
+    # @return [Boolean]
+    def persisted?
+      target != OpenStruct.new
+    end
+
+    # Send <tt>:save</tt> method to all mountings in list. Will return +true+
+    # only if all savings are positive.
+    #
+    # @param [Array<FlatMap::OpenMapper>] mountings
+    # @return [Boolean]
+    def save_mountings(mountings)
+      mountings.map{ |mount| mount.save }.all?
+    end
+    private :save_mountings
+
+    # Return +true+ if the mapper is valid, i.e. if it is valid itself, and if
+    # all mounted mappers (traits and other mappers) are also valid.
+    #
+    # Accepts any parameters, but doesn't use them to be compatible with
+    # ActiveRecord calls.
+    #
+    # @return [Boolean]
+    def valid?(*)
+      res = trait_mountings.map(&:valid?).all?
+      res = super && res # we do want to call super
+      mounting_res = mapper_mountings.map(&:valid?).all?
+      consolidate_errors!
+      res && mounting_res
+    end
+
+    # Consolidate the errors of all mounted mappers to a set of errors of +self+.
+    #
+    # @return [Array<ActiveModel::Errors>]
+    def consolidate_errors!
+      mountings.map(&:errors).each do |errs|
+        errors.messages.merge!(errs.to_hash){ |key, old, new| old.concat(new) }
+      end
+    end
+    private :consolidate_errors!
+
+    # Overridden to use {FlatMap::Errors} instead of ActiveModel ones.
+    #
+    # @return [FlatMap::Errors]
+    def errors
+      @errors ||= FlatMap::Errors.new(self)
+    end
+
+    # Extract Rails multiparam parameters from the +params+, modifying
+    # original hash. Behaves somewhat like
+    # {ActiveRecord::AttributeAssignment#extract_callstack_for_multiparameter_attributes}
+    # See this method for more details.
+    #
+    # @param [Hash] params
+    # @return [Array<FlatMap::Mapping>] return value is not used, original
+    #   +params+ hash is modified instead and used later on.
+    def extract_multiparams!(params)
+      all_mappings.select(&:multiparam?).each do |mapping|
+        param_keys = params.keys.
+          select { |key| key.to_s =~ /#{mapping.full_name}\(\d+[isf]\)/ }.
+          sort_by{ |key| key.to_s[/\((\d+)\w*\)/, 1].to_i }
+
+        next if param_keys.empty?
+
+        args = param_keys.inject([]) do |values, key|
+          value = params.delete key
+          type  = key[/\(\d+(\w*)\)/, 1]
+          value = value.send("to_#{type}") unless type.blank?
+
+          values.push value
+          values
+        end
+
+        params[mapping.name] = mapping.multiparam.new(*args) rescue nil
+      end
+    end
+    private :extract_multiparams!
+  end
+end