flat_map 0.0.3

data/lib/flat_map/mapper/skipping.rb

@@ -0,0 +1,45 @@
+module FlatMap
+  # This helper module slightly enhances functionality of the
+  # {BaseMapper::Skipping} module for most commonly used +ActiveRecord+ targets.
+  # This is done to improve modularity of the {FlatMap} mappers.
+  module Mapper::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/mapper/targeting.rb

@@ -0,0 +1,130 @@
+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.
+  module Mapper::Targeting
+    # 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::Concern
+
+    included do
+      define_callbacks :save
+
+      # 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
+      # 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::Mapper] mapper
+      def build(*traits, &block)
+        new(target_class.new, *traits, &block)
+      end
+
+      # 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::Mapper)
+        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/mapping.rb

@@ -0,0 +1,124 @@
+module FlatMap
+  # Encapsulates mapping concept used by mappers. Each mapping belongs to
+  # a particular mapper and has its own reader and writer objects.
+  class Mapping
+    extend ActiveSupport::Autoload
+
+    autoload :Reader
+    autoload :Writer
+    autoload :Factory
+
+    attr_reader :mapper, :name, :full_name, :target_attribute
+    attr_reader :reader, :writer
+    attr_reader :multiparam
+
+    delegate :target, :to => :mapper
+    delegate :write,  :to => :writer, :allow_nil => true
+    delegate :read,   :to => :reader, :allow_nil => true
+
+    # Initialize a mapping, passing to it a +mapper+, which is
+    # a gateway to actual +target+, +name+, which is an external
+    # identifier, +target_attribute+, which is used to access
+    # actual information of the +target+, and +options+.
+    #
+    # @param [FlatMap::Mapper] mapper
+    # @param [Symbol]                name
+    # @param [Symbol]                target_attribute
+    # @param [Hash]                  options
+    # @option [Symbol, Proc] :reader specifies how value will
+    #   be read from the +target+
+    # @option [Symbol] :format specifies additional processing
+    #   of the value on reading
+    # @option [Symbol, Proc] :writer specifies how value will
+    #   be written to the +target+
+    # @option [Class] :multiparam specifies multiparam Class,
+    #   object of which will be instantiated on writing
+    #   multiparam attribute passed from the Rails form
+    def initialize(mapper, name, target_attribute, options = {})
+      @mapper           = mapper
+      @name             = name
+      @target_attribute = target_attribute
+
+      @full_name = mapper.suffixed? ? :"#{@name}_#{mapper.suffix}" : name
+
+      @multiparam = options[:multiparam]
+
+      fetch_reader(options)
+      fetch_writer(options)
+    end
+
+    # Return +true+ if the mapping was created with the <tt>:multiparam</tt>
+    # option set.
+    #
+    # @return [Boolean]
+    def multiparam?
+      !!@multiparam
+    end
+
+    # Lookup the passed hash of params for the key that corresponds
+    # to the +full_name+ of +self+, and write it if it is present.
+    #
+    # @param [Hash] params
+    # @return [Object] value assigned
+    def write_from_params(params)
+      write(params[full_name]) if params.key?(full_name) && writer.present?
+    end
+
+    # Return a hash of a single key => value pair, where key
+    # corresponds to +full_name+ and +value+ to value read from
+    # +target+. If +reader+ is not set, return an empty hash.
+    #
+    # @return [Hash]
+    def read_as_params
+      reader ? {full_name => read} : {}
+    end
+
+    # Instantiate a +reader+ object based on the <tt>:reader</tt>
+    # and <tt>:format</tt> values of +options+.
+    #
+    # @param [Hash] options
+    # @return [FlatMap::Mapping::Reader::Basic]
+    def fetch_reader(options)
+      options_reader = options[:reader]
+
+      @reader =
+        case options_reader
+        when Symbol, String
+          Reader::Method.new(self, options_reader)
+        when Proc
+          Reader::Proc.new(self, options_reader)
+        when false
+          nil
+        else
+          if options.key?(:format) then
+            Reader::Formatted.new(self, options[:format])
+          else
+            Reader::Basic.new(self)
+          end
+        end
+    end
+    private :fetch_reader
+
+    # Instantiate a +writer+ object based on the <tt>:writer</tt>
+    # value of +options+.
+    #
+    # @param [Hash] options
+    # @return [FlatMap::Mapping::Writer::Basic]
+    def fetch_writer(options)
+      options_writer = options[:writer]
+
+      @writer =
+        case options_writer
+        when Symbol, String
+          Writer::Method.new(self, options_writer)
+        when Proc
+          Writer::Proc.new(self, options_writer)
+        when false
+          nil
+        else
+          Writer::Basic.new(self)
+        end
+    end
+    private :fetch_writer
+  end
+end

data/lib/flat_map/mapping/factory.rb

@@ -0,0 +1,21 @@
+module FlatMap
+  # Factory objects store mapping definitions within mapper class and are
+  # used eventually to generate mapping objects for a particular mapper.
+  class Mapping::Factory
+    # Simply store all arguments necessary to create a new mapping for
+    # a specific mapper.
+    #
+    # @param [*Object] args
+    def initialize(*args)
+      @args = args
+    end
+
+    # Return a new mapping, initialized by +mapper+ and <tt>@args</tt>.
+    #
+    # @param [FlatMap::Mapper] mapper
+    # @return [FlatMap::Mapping]
+    def create(mapper)
+      Mapping.new(mapper, *@args)
+    end
+  end
+end

data/lib/flat_map/mapping/reader.rb

@@ -0,0 +1,12 @@
+module FlatMap
+  # Reader module hosts various readers that are used by
+  # mappings for reading and returning values.
+  module Mapping::Reader
+    extend ActiveSupport::Autoload
+
+    autoload :Basic
+    autoload :Method
+    autoload :Proc
+    autoload :Formatted
+  end
+end

data/lib/flat_map/mapping/reader/basic.rb

@@ -0,0 +1,28 @@
+module FlatMap
+  module Mapping::Reader
+    # Basic reader simply sends a mapped attribute to the target
+    # and returns the result value.
+    class Basic
+      attr_reader :mapping
+
+      delegate :target, :target_attribute, :to => :mapping
+
+      # Initialize the reader with a mapping.
+      #
+      # @param [FlatMap::Mapping] mapping
+      def initialize(mapping)
+        @mapping = mapping
+      end
+
+      # Send the attribute method to the target and return its value.
+      # As a base class for readers, it allows to pass additional
+      # arguments when reading value (for example, used by :enum
+      # format of {Formatted} reader)
+      #
+      # @return [Object] value returned by reading
+      def read(*)
+        target.send(target_attribute)
+      end
+    end
+  end
+end

data/lib/flat_map/mapping/reader/formatted.rb

@@ -0,0 +1,45 @@
+module FlatMap
+  module Mapping::Reader
+    # Formatted reader reads the value the same as Basic reader does, but
+    # additionally performs value postprocessing. All processing methods
+    # are defined within {Formatted::Formats} module. The method is chosen
+    # based on the :format option when the mapping is defined.
+    class Formatted < Basic
+      extend ActiveSupport::Autoload
+      autoload :Formats
+
+      include Formats
+
+      # Initialize the reader with a +mapping+ and a +format+.
+      #
+      # @param [FlatMap::Mapping] mapping
+      # @param [Symbol] format
+      def initialize(mapping, format)
+        @mapping, @format = mapping, format
+      end
+
+      # Read the value just like the {Basic} reader does, but
+      # additionally send the returned value to its format method.
+      #
+      # Additional arguments will be passed to formatting function
+      # of the mapping's format.
+      #
+      # @return [Object] formatted value
+      def read(*args)
+        format_value(super, *args)
+      end
+
+      # Send the +value+ to the format method, defined in the {Format}
+      # module and specified upon reader initialization.
+      #
+      # Additional optional arguments are passed as well.
+      #
+      # @param [Object] value
+      # @return [Object] formatted value
+      def format_value(value, *args)
+        send(@format, value, *args)
+      end
+      private :format_value
+    end
+  end
+end

data/lib/flat_map/mapping/reader/formatted/formats.rb

@@ -0,0 +1,28 @@
+module FlatMap
+  module Mapping::Reader
+    # Hosts various formats that can be applied to values read by mappings
+    # for post-processing.
+    module Formatted::Formats
+      if defined? I18n
+        # Pass +value+ to <tt>I18n::l</tt> method.
+        def i18n_l(value)
+          I18n::l(value) if value
+        end
+      end
+
+      if defined? PowerEnum
+        # Return the specified +property+ of a +value+ which
+        # is supposed to be an +enum+ record. By default,
+        # uses <tt>:name</tt>. However, <tt>:description</tt>
+        # might be also useful for UI purposes.
+        #
+        # @param [Object] value
+        # @param [Symbol] property
+        # @return [Object]
+        def enum(value, property = :name)
+          value.send(property) if value
+        end
+      end
+    end
+  end
+end

data/lib/flat_map/mapping/reader/method.rb

@@ -0,0 +1,25 @@
+module FlatMap
+  module Mapping::Reader
+    # Method mapper calls a method, defined by the mapper, sending
+    # the mapping object to it as an argument.
+    class Method < Basic
+      delegate :mapper, :to => :mapping
+
+      # Initialize the reader with a +mapping+ and a +method+.
+      #
+      # @param [FlatMap::Mapping] mapping
+      # @param [Symbol] method name
+      def initialize(mapping, method)
+        @mapping, @method = mapping, method
+      end
+
+      # Send the <tt>@method</tt> to the mapping's mapper, passing
+      # the mapping itself to it.
+      #
+      # @return [Object] value returned by reader
+      def read
+        mapper.send(@method, mapping)
+      end
+    end
+  end
+end