HornsAndHooves-flat_map 0.2.0

data/lib/flat_map/model_mapper/persistence.rb

@@ -0,0 +1,108 @@
+module FlatMap
+  # This module enhances and modifies original FlatMap::OpenMapper::Persistence
+  # functionality for ActiveRecord models as targets.
+  module ModelMapper::Persistence
+    extend ActiveSupport::Concern
+
+    included do
+      # Writer of the target class name. Allows manual control over target
+      # class of the mapper, for example:
+      #
+      #   class CustomerMapper
+      #     self.target_class_name = 'Customer::Active'
+      #   end
+      class_attribute :target_class_name
+    end
+
+    # ModelMethods class macros
+    module ClassMethods
+      # Find a record of the +target_class+ by +id+ and use it as a
+      # target for a new mapper, with a list of passed +traits+ applied
+      # to it.
+      #
+      # @param [#to_i] id of the record
+      # @param [*Symbol] traits
+      # @return [FlatMap::Mapper] mapper
+      def find(id, *traits, &block)
+        new(target_class.find(id), *traits, &block)
+      end
+
+      # Fetch a class for the target of the mapper.
+      #
+      # @return [Class] class
+      def target_class
+        (target_class_name || default_target_class_name).constantize
+      end
+
+      # Return target class name based on name of the ancestor mapper
+      # that is closest to {FlatMap::Mapper}, which may be +self+.
+      #
+      #   class VehicleMapper
+      #     # some definitions
+      #   end
+      #
+      #   class CarMapper < VehicleMapper
+      #     # some more definitions
+      #   end
+      #
+      #   CarMapper.target_class # => Vehicle
+      #
+      # @return [String]
+      def default_target_class_name
+        ancestor_classes  = ancestors.select{ |ancestor| ancestor.is_a? Class }
+        base_mapper_index = ancestor_classes.index(::FlatMap::ModelMapper)
+        ancestor_classes[base_mapper_index - 1].name[/^([\w:]+)Mapper.*$/, 1]
+      end
+    end
+
+    # Return a 'mapper' string as a model_name. Used by Rails FormBuilder.
+    #
+    # @return [String]
+    def model_name
+      'mapper'
+    end
+
+    # Delegate to the target's #to_key method.
+    # @return [String]
+    def to_key
+      target.to_key
+    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)
+      res = if valid?
+        ActiveRecord::Base.transaction do
+          save
+        end
+      end
+      !!res
+    end
+
+    # Save +target+
+    #
+    # @return [Boolean]
+    def save_target
+      return true if owned?
+      target.respond_to?(:save) ? target.save(:validate => false) : true
+    end
+
+    # Delegate persistence to target.
+    #
+    # @return [Boolean]
+    def persisted?
+      target.respond_to?(:persisted?) ? target.persisted? : false
+    end
+
+    # Delegate #id to target, if possible.
+    #
+    # @return [Fixnum, nil]
+    def id
+      target.id if target.respond_to?(:id)
+    end
+  end
+end

data/lib/flat_map/model_mapper/skipping.rb

@@ -0,0 +1,45 @@
+module FlatMap
+  # This helper module slightly enhances ofunctionality of the
+  # {FlatMap::OpenMapper::Skipping} module for most commonly
+  # used +ActiveRecord+ targets.
+  module ModelMapper::Skipping
+    # Extend original #skip! method for Rails-models-based targets
+    #
+    # Note that this will mark the target record as
+    # destroyed if it is a new record. Thus, this
+    # record will not be a subject of Rails associated
+    # validation procedures, and will not be saved as an
+    # associated record.
+    #
+    # @return [Object]
+    def skip!
+      super
+      if target.is_a?(ActiveRecord::Base)
+        if target.new_record?
+          # Using the instance variable directly as {ActiveRecord::Base#delete}
+          # will freeze the record.
+          target.instance_variable_set('@destroyed', true)
+        else
+          # Using reload instead of reset_changes! to reset associated nested
+          # model changes also
+          target.reload
+        end
+      end
+    end
+
+    # Extend original #use! method for Rails-models-based targets, as
+    # acoompanied to #skip! method.
+    #
+    # @return [Object]
+    def use!
+      super
+      if target.is_a?(ActiveRecord::Base)
+        if target.new_record?
+          target.instance_variable_set('@destroyed', false)
+        else
+          all_nested_mountings.each(&:use!)
+        end
+      end
+    end
+  end
+end

data/lib/flat_map/open_mapper.rb

@@ -0,0 +1,113 @@
+module FlatMap
+  # Base Mapper that can be used for mounting other mappers, handling business logic,
+  # etc. For the intentional usage of mappers, pleas see {ModelMapper}
+  class OpenMapper
+    # Raised when mapper is initialized with no target defined
+    class NoTargetError < ArgumentError
+      # Initializes exception with a name of mapper class.
+      #
+      # @param [Class] mapper_class class of mapper being initialized
+      def initialize(mapper_class)
+        super("Target object is required to initialize #{mapper_class.name}")
+      end
+    end
+
+    extend ActiveSupport::Autoload
+
+    autoload :Mapping
+    autoload :Mounting
+    autoload :Traits
+    autoload :Factory
+    autoload :AttributeMethods
+    autoload :Persistence
+    autoload :Skipping
+
+    include Mapping
+    include Mounting
+    include Traits
+    include AttributeMethods
+    include ActiveModel::Validations
+    include Persistence
+    include Skipping
+
+    attr_writer :host, :suffix
+    attr_reader :target, :traits
+    attr_accessor :owner, :name
+
+    # Callback to dup mappings and mountings on inheritance.
+    # The values are cloned from actual mappers (i.e. something
+    # like CustomerAccountMapper, since it is useless to clone
+    # empty values of FlatMap::Mapper).
+    #
+    # Note: those class attributes are defined in {Mapping}
+    # and {Mounting} modules.
+    def self.inherited(subclass)
+      subclass.mappings  = mappings.dup
+      subclass.mountings = mountings.dup
+    end
+
+    # Initializes +mapper+ with +target+ and +traits+, which are
+    # used to fetch proper list of mounted mappers. Raises error
+    # if target is not specified.
+    #
+    # @param [Object] target Target of mapping
+    # @param [*Symbol] traits List of traits
+    # @raise [FlatMap::Mapper::NoTargetError]
+    def initialize(target, *traits)
+      raise NoTargetError.new(self.class) unless target
+
+      @target, @traits = target, traits
+
+      if block_given?
+        singleton_class.trait :extension, &Proc.new
+      end
+    end
+
+    # Return a simple string representation of +mapper+. Done so to
+    # avoid really long inspection of internal objects (target -
+    # usually AR model, mountings and mappings)
+    # @return [String]
+    def inspect
+      to_s
+    end
+
+    # Return +true+ if +mapper+ is owned. This means that current
+    # mapper is actually a trait. Thus, it is a part of an owner
+    # mapper.
+    #
+    # @return [Boolean]
+    def owned?
+      owner.present?
+    end
+
+    # If mapper was mounted by another mapper, host is the one who
+    # mounted +self+.
+    #
+    # @return [FlatMap::Mapper]
+    def host
+      owned? ? owner.host : @host
+    end
+
+    # Return +true+ if mapper is hosted, i.e. it is mounted by another
+    # mapper.
+    #
+    # @return [Boolean]
+    def hosted?
+      host.present?
+    end
+
+    # +suffix+ reader. Delegated to owner for owned mappers.
+    #
+    # @return [String, nil]
+    def suffix
+      owned? ? owner.suffix : @suffix
+    end
+
+    # Return +true+ if +suffix+ is present.
+    #
+    # @return [Boolean]
+    def suffixed?
+      suffix.present?
+    end
+  end
+end

data/lib/flat_map/open_mapper/attribute_methods.rb

@@ -0,0 +1,55 @@
+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 OpenMapper::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 ||
+          self.class.protected_instance_methods.include?(name)
+        return super
+      end
+
+      mappings    = all_mappings
+      valid_names = mappings.map do |mapping|
+        full_name = mapping.full_name
+        [full_name, "#{full_name}=".to_sym]
+      end
+      valid_names.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|
+          full_name = mapping.full_name
+
+          define_method(full_name){ |*args| mapping.read(*args) }
+
+          define_method("#{full_name}=") do |value|
+            mapping.write(value)
+          end
+        end
+      end
+    end
+    private :attribute_methods
+  end
+end

data/lib/flat_map/open_mapper/factory.rb

@@ -0,0 +1,244 @@
+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 OpenMapper::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::OpenMapper}
+    def mapper_class
+      @mapper_class ||= begin
+        case
+        when traited?        then @identifier
+        when @options[:open] then open_mapper_class
+        when @options[:mapper_class] then @options[:mapper_class]
+        else
+          class_name = @options[:mapper_class_name] || "#{name.to_s.camelize}Mapper"
+          class_name.constantize
+        end
+      end
+    end
+
+    # Return descendant of +OpenMapper+ class to be used when mounting
+    # open mappers.
+    #
+    # @return [Class]
+    def open_mapper_class
+      klass = Class.new(OpenMapper)
+      klass_name = "#{name.to_s.camelize}Mapper"
+      klass.singleton_class.send(:define_method, :name){ klass_name }
+      klass
+    end
+
+    # Return +true+ if mapper to me mounted is +ModelMapper+
+    #
+    # @return [Boolean]
+    def model_mount?
+      mapper_class < ModelMapper
+    end
+
+    # Return +true+ if mapper to me mounted is not +ModelMapper+, i.e. +OpenMapper+.
+    #
+    # @return [Boolean]
+    def open_mount?
+      !model_mount?
+    end
+
+    # Fetch the target for the mapper being created based on target of a host mapper.
+    #
+    # @param [FlatMap::OpenMapper] mapper Host mapper
+    # @return [Object] target for new mapper
+    def fetch_target_from(mapper)
+      owner_target = mapper.target
+
+      return owner_target if traited?
+
+      if open_mount?
+        explicit_target(mapper) || new_target
+      else
+        explicit_target(mapper) ||
+          target_from_association(owner_target) ||
+          target_from_name(owner_target) ||
+          new_target
+      end
+    end
+
+    # Return new instance of +target_class+ of the mapper.
+    #
+    # @return [Object]
+    def new_target
+      mapper_class.target_class.new
+    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 [FlatMap::OpenMapper] mapper
+    # @return [Object, nil] target for new mapper.
+    def explicit_target(mapper)
+      if @options.key?(:target)
+        target = @options[:target]
+        case target
+        when Proc   then target.call(mapper.target)
+        when Symbol then mapper.send(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.is_a?(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
+      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::OpenMapper] mapper
+    # @return [Symbol]
+    def fetch_save_order(mapper)
+      return :after unless mapper.is_a?(ModelMapper)
+
+      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::OpenMapper] 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
+      new_one = mapper_class.new(fetch_target_from(mapper), *(traits + owner_traits).uniq, &@extension)
+      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? do |factory|
+          factory.traited? &&
+            factory.required_for_any_trait?(traits)
+        end
+    end
+  end
+end