flat_map 0.0.3

data/lib/flat_map/base_mapper/persistence.rb

@@ -0,0 +1,145 @@
+module FlatMap
+  # This module provides persistence functionality for mappers. Note
+  # that term of persistence here does not imply storing information
+  # in database or other place. This module provides methods for
+  # saving operation as a work flow of applying parameters to mapper
+  # and all of its mounted mappers in a right way, running callbacks,
+  # etc.
+  #
+  # See {Mapper::Targeting} for a place where mapper targets are
+  # actually get persisted / updated.
+  #
+  # 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 BaseMapper::Persistence
+    # 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
+
+    # Perform target save with callbacks call
+    #
+    # @return [Boolean]
+    def shallow_save
+      run_callbacks(:save){ save_target }
+    end
+
+    # Send <tt>:save</tt> method to all mountings in list. Will return +true+
+    # only if all savings are positive.
+    #
+    # @param [Array<FlatMap::BaseMapper>] 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

data/lib/flat_map/base_mapper/skipping.rb

@@ -0,0 +1,62 @@
+module FlatMap
+  # This helper module provides helper functionality that allow to
+  # exclude specific mapper from a processing chain.
+  module BaseMapper::Skipping
+    # Mark self as skipped, i.e. it will not be subject of
+    # validation and saving chain.
+    #
+    # @return [Object]
+    def skip!
+      @_skip_processing = true
+    end
+
+    # Remove "skip" mark from +self+ and "destroyed" flag from
+    # the target.
+    #
+    # @return [Object]
+    def use!
+      @_skip_processing = nil
+    end
+
+    # Return +true+ if +self+ was marked for skipping.
+    #
+    # @return [Boolean]
+    def skipped?
+      !!@_skip_processing
+    end
+
+    # Override {FlatMap::BaseMapper::Persistence#valid?} to
+    # force it to return +true+ if +self+ is marked for skipping.
+    #
+    # @param [Symbol] context useless context parameter to make it compatible with
+    #   ActiveRecord models.
+    #
+    # @return [Boolean]
+    def valid?(context = nil)
+      skipped? || super
+    end
+
+    # Override {FlatMap::BaseMapper::Persistence#save} method to
+    # force it to return +true+ if +self+ is marked for skipping.
+    #
+    # @return [Boolean]
+    def save
+      skipped? || super
+    end
+
+    # Override {FlatMap::BaseMapper::Persistence#shallow_save} method
+    # to make it possible to skip traits.
+    #
+    # @return [Boolean]
+    def shallow_save
+      skipped? || super
+    end
+
+    # Mark self as used and then delegated to original
+    # {FlatMap::BaseMapper::Persistence#write}.
+    def write(*)
+      use!
+      super
+    end
+  end
+end

data/lib/flat_map/base_mapper/traits.rb

@@ -0,0 +1,94 @@
+module FlatMap
+  # This small module allows mappers to define traits, which technically
+  # means mounting anonymous mappers, attached to host one.
+  module BaseMapper::Traits
+    extend ActiveSupport::Concern
+
+    # Traits class macros
+    module ClassMethods
+      # Define a trait for a mapper class. In implementation terms, a trait
+      # is nothing more than a mounted mapper, owned by a host mapper.
+      # It shares all mappings with it.
+      # The block is passed as a body of the anonymous mapper class.
+      #
+      # @param [Symbol] name
+      def trait(name, &block)
+        base_class        = self < FlatMap::Mapper ? FlatMap::Mapper : FlatMap::EmptyMapper
+        mapper_class      = Class.new(base_class, &block)
+        mapper_class_name = "#{ancestors.first.name}#{name.to_s.camelize}Trait"
+        mapper_class.singleton_class.send(:define_method, :name){ mapper_class_name }
+        mount mapper_class, :trait_name => name
+      end
+    end
+
+    # Override the original {FlatMap::BaseMapper::Mounting#mountings}
+    # method to filter out those traited mappers that are not required for
+    # trait setup of +self+. Also, handle any inline extension that may be
+    # defined on the mounting mapper, which is attached as a singleton trait.
+    #
+    # @return [Array<FlatMap::BaseMapper>]
+    def mountings
+      @mountings ||= begin
+        mountings = self.class.mountings.
+                               reject{ |factory|
+                                 factory.traited? &&
+                                 !factory.required_for_any_trait?(traits)
+                               }
+        mountings.concat(singleton_class.mountings)
+        mountings.map{ |factory| factory.create(self, *traits) }
+      end
+    end
+
+    # Return a list of all mountings that represent full picture of +self+, i.e.
+    # +self+ and all traits, including deeply nested, that are mounted on self
+    #
+    # @return [Array<FlatMap::BaseMapper>]
+    def self_mountings
+      mountings.select(&:owned?).map{ |mount| mount.self_mountings }.flatten.concat [self]
+    end
+
+    # Try to find trait mapper with name that corresponds to +trait_name+
+    # Used internally to manipulate such mappers (for example, skip some traits)
+    # in some scenarios.
+    #
+    # @param [Symbol] trait_name
+    # @return [FlatMap::BaseMapper, nil]
+    def trait(trait_name)
+      self_mountings.find{ |mount| mount.class.name.underscore =~ /#{trait_name}_trait$/ }
+    end
+
+    # Return :extension trait, if present
+    #
+    # @return [FlatMap::BaseMapper]
+    def extension
+      trait(:extension)
+    end
+
+    # Return only mountings that are actually traits for host mapper.
+    #
+    # @return [Array<FlatMap::BaseMapper>]
+    def trait_mountings
+      result = mountings.select{ |mount| mount.owned? }
+      # mapper extension has more priority then traits, and
+      # has to be processed first.
+      result.unshift(result.pop) if result.length > 1 && result[-1].extension?
+      result
+    end
+    protected :trait_mountings
+
+    # Return only mountings that correspond to external mappers.
+    #
+    # @return [Array<FlatMap::BaseMapper>]
+    def mapper_mountings
+      mountings.select{ |mount| !mount.owned? }
+    end
+    protected :mapper_mountings
+
+    # Return +true+ if +self+ is extension of host mapper.
+    #
+    # @return [Boolean]
+    def extension?
+      owned? && self.class.name =~ /ExtensionTrait$/
+    end
+  end
+end

data/lib/flat_map/empty_mapper.rb

@@ -0,0 +1,29 @@
+module FlatMap
+  # +EmptyMapper+ behaves in a very same way as targeted {Mapper Mappers}
+  # with only distinction of absence of required target. That makes them
+  # a platform for mounting other mappers and placing control structures
+  # of business logic.
+  #
+  # Form more detailed information on what mappers are and their API
+  # refer to {Mapper}.
+  class EmptyMapper < BaseMapper
+    # Initializes +mapper+ with +traits+, which are
+    # used to fetch proper list of mounted mappers.
+    #
+    # @param [*Symbol] traits List of traits
+    def initialize(*traits)
+      @traits = traits
+
+      if block_given?
+        singleton_class.trait :extension, &Proc.new
+      end
+    end
+
+    # Return +true+ since there's no target.
+    #
+    # @return [true]
+    def save_target
+      true
+    end
+  end
+end

data/lib/flat_map/errors.rb

@@ -0,0 +1,57 @@
+module FlatMap
+  # Inherited from ActiveModel::Errors to slightly ease work when writing
+  # attributes in a way that can possibly result in an exception. If we'd
+  # want to add errors on that point and see them in the resulting object,
+  # we have to preserve them before owner's <tt>run_validations!</tt> method
+  # call, since it will clear all the errors.
+  #
+  # After validation complete, preserved errors are added to the list of
+  # the original ones.
+  #
+  # Usecase scenario:
+  #
+  #   class MyMapper < FlatMap::Mapper
+  #     def custom_attr=(value)
+  #       raise MyException, 'cannot be foo' if value == 'foo'
+  #     rescue MyException => e
+  #       errors.preserve :custom_attr, e.message
+  #     end
+  #   end
+  #
+  #   mapper = MyMapper.new(MyObject.new)
+  #   mapper.apply(:custom_attr => 'foo') # => false
+  #   mapper.errors[:custom_attr] # => ['cannot be foo']
+  class Errors < ActiveModel::Errors
+    # Add <tt>@preserved_errors</tt> to object.
+    def initialize(*)
+      @preserved_errors = {}
+      super
+    end
+
+    # Postpone error. It will be added to <tt>@messages</tt> later,
+    # on <tt>empty?</tt> method call.
+    #
+    # @param [String, Symbol] key
+    # @param [String] message
+    def preserve(key, message)
+      @preserved_errors[key] = message
+    end
+
+    # Overloaded to add <tt>@preserved_errors</tt> to the list of
+    # original <tt>@messages</tt>. <tt>@preserved_errors</tt> are
+    # cleared after this method call.
+    def empty?
+      unless @preserved_errors.empty?
+        @preserved_errors.each{ |key, value| add(key, value) }
+        @preserved_errors.clear
+      end
+      super
+    end
+
+    # Overridden to add suffixing support for mappings of mappers with name suffix
+    def add(attr, *args)
+      attr = :"#{attr}_#{@base.suffix}" if attr != :base && @base.suffixed?
+      super
+    end
+  end
+end

data/lib/flat_map/mapper.rb

@@ -0,0 +1,213 @@
+module FlatMap
+  # == Mapper
+  #
+  # FlatMap mappers are designed to provide complex set of data, distributed over
+  # associated AR models, in the simple form of a plain hash. They accept a plain
+  # hash of the same format and distribute its values over deeply nested AR models.
+  #
+  # To achieve this goal, Mapper uses three major concepts: Mappings, Mountings and
+  # Traits.
+  #
+  # === Mappings
+  #
+  # Mappings are defined view Mapper.map method. They represent a simple one-to-one
+  # relation between target attribute and a mapper, extended by additional features
+  # for convenience. The best way to show how they work is by example:
+  #
+  #   class CustomerMapper < FlatMap::Mapper
+  #     # When there is no need to rename attributes, they can be passed as array:
+  #     map :first_name, :last_name
+  #
+  #     # When hash is used, it will map field name to attribute name:
+  #     map :dob => :date_of_birth
+  #
+  #     # Also, additional options can be used:
+  #     map :name_suffix, :format => :enum
+  #     map :password, :reader => false, :writer => :assign_password
+  #
+  #     # Or you can combine all definitions together if they all are common:
+  #     map :first_name, :last_name,
+  #         :dob    => :date_of_birth,
+  #         :suffix => :name_suffix,
+  #         :reader => :my_custom_reader
+  #   end
+  #
+  # When mappings are defined, one can read and write values using them:
+  #
+  #   mapper = CustomerMapper.find(1)
+  #   mapper.read          # => {:first_name => 'John', :last_name => 'Smith', :dob => '02/01/1970'}
+  #   mapper.write(params) # will assign same-looking hash of arguments
+  #
+  # Following options may be used when defining mappings:
+  # [<tt>:format</tt>] Allows to additionally process output value on reading it. All formats are
+  #                    defined within FlatMap::Mapping::Reader::Formatted::Formats and
+  #                    specify the actual output of the mapping
+  # [<tt>:reader</tt>] Allows you to manually control reader value of a mapping, or a group of
+  #                    mappings listed on definition. When String or Symbol is used, will call
+  #                    a method, defined by mapper class, and pass mapping object to it. When
+  #                    lambda is used, mapper's target (the model) will be passed to it.
+  # [<tt>:writer</tt>] Just like with the :reader option, allows to control how value is assigned
+  #                    (written). Works the same way as :reader does, but additionally value is
+  #                    sent to both mapper method and lambda.
+  # [<tt>:multiparam</tt>] If used, multiparam attributes will be extracted from params, when
+  #                        those are passed for writing. Class should be passed as a value for
+  #                        this option. Object of this class will be initialized with the arguments
+  #                        extracted from params hash.
+  #
+  # === Mountings
+  #
+  # Mappers may be mounted on top of each other. This ability allows host mapper to gain all the
+  # mappings of the mounted mapper, thus providing more information for external usage (both reading
+  # and writing). Usually, target for mounted mapper may be obtained from association of target of
+  # the host mapper itself, but may be defined manually.
+  #
+  #   class CustomerMapper < FlatMap::Mapper
+  #     map :first_name, :last_name
+  #   end
+  #
+  #   class CustomerAccountMapper < FlatMap::Mapper
+  #     map :source, :brand, :format => :enum
+  #
+  #     mount :customer
+  #   end
+  #
+  #   mapper = CustomerAccountMapper.find(1)
+  #   mapper.read # => {:first_name => 'John', :last_name => 'Smith', :source => nil, :brand => 'FTW'}
+  #   mapper.write(params) # Will assign params for both CustomerAccount and Customer records
+  #
+  # The following options may be used when mounting a mapper:
+  # [<tt>:mapper_class</tt>] Specifies mapper class if it cannot be determined from mounting itself
+  # [<tt>:target</tt>] Allows to manually specify target for the new mapper. May be oject or lambda
+  #                    with arity of one that accepts host mapper target as argument. Comes in handy
+  #                    when target cannot be obviously detected or requires additional setup:
+  #                    <tt>mount :title, :target => lambda{ |customer| customer.title_customers.build.build_title }</tt>
+  # [<tt>:traits</tt>] Specifies list of traits to be used by mounted mapper
+  # [<tt>:suffix</tt>] Specifies the suffix that will be appended to all mappings and mountings of mapper,
+  #                    as well as mapper name itself.
+  #
+  # === Traits
+  #
+  # Traits allow mappers to encapsulate named sets of additional definitions, and use them optionally
+  # on mapper initialization. Everything that can be defined within the mapper may be defined within
+  # the trait. In fact, from the implementation perspective traits are mappers themselves that are
+  # mounted on the host mapper.
+  #
+  #   class CustomerAccountMapper < FlatMap::Mapper
+  #     map :brand, :format => :enum
+  #
+  #     trait :with_email do
+  #       map :source, :format => :enum
+  #
+  #       mount :email_address
+  #
+  #       trait :with_email_phones_residence do
+  #         mount :customer, :traits => [:with_phone_numbers, :with_residence]
+  #       end
+  #     end
+  #   end
+  #
+  #   CustomerAccountMapper.find(1).read # => {:brand => 'TLP'}
+  #   CustomerAccountMapper.find(1, :with_email).read # => {:brand => 'TLP', :source => nil, :email_address => 'j.smith@gmail.com'}
+  #   CustomerAccountMapper.find(1, :with_email_phone_residence).read # => :brand, :source, :email_address, phone numbers,
+  #                                    #:residence attributes - all will be available for reading and writing in plain hash
+  #
+  # === Extensions
+  #
+  # When mounting a mapper, one can pass an optional block. This block is used as an extension for a mounted
+  # mapper and acts as an anonymous trait. For example:
+  #
+  #   class CustomerAccountMapper < FlatMap::Mapper
+  #     mount :customer do
+  #       map :dob => :date_of_birth, :format => :i18n_l
+  #       validates_presence_of :dob
+  #
+  #       mount :unique_identifier
+  #
+  #       validates_acceptance_of :mandatory_agreement, :message => "You must check this box to continue"
+  #     end
+  #   end
+  #
+  # === Validation
+  #
+  # <tt>FlatMap::Mapper</tt> includes <tt>ActiveModel::Validations</tt> module, allowing each model to
+  # perform its own validation routines before trying to save its target (which is usually AR model). Mapper
+  # validation is very handy when mappers are used with Rails forms, since there no need to lookup for a
+  # deeply nested errors hash of the AR models to extract error messages. Mapper validations will attach
+  # messages to mapping names.
+  #
+  # Mapper validations become even more useful when used within traits, providing way of very flexible validation sets.
+  #
+  # === Callbacks
+  #
+  # Since mappers include <tt>ActiveModel::Validation</tt>, they already support ActiveSupport's callbacks.
+  # Additionally, <tt>:save</tt> callbacks have been defined (i.e. there have been define_callbacks <tt>:save</tt>
+  # call for <tt>FlatMap::Mapper</tt>). This allows you to control flow of mapper saving:
+  #
+  #   set_callback :save, :before, :set_model_validation
+  #
+  #   def set_model_validation
+  #     target.use_validation :some_themis_validation
+  #   end
+  #
+  # === Skipping
+  #
+  # In some cases, it is required to omit mapper processing after it has been created within mounting chain. If
+  # <tt>skip!</tt> method is called on mapper, it will return <tt>true</tt> for <tt>valid?</tt> and <tt>save</tt>
+  # method calls without performing any other operations. For example:
+  #
+  #   class CustomerMapper < FlatMap::Mapper
+  #     # some definitions
+  #
+  #     trait :product_selection do
+  #       attr_reader :selected_product_id
+  #
+  #       mount :product
+  #
+  #       set_callback :validate, :before, :ignore_new_product
+  #
+  #       def ignore_new_bank_account
+  #         mounting(:product).skip! if product_selected?
+  #       end
+  #
+  #       # some more definitions
+  #     end
+  #   end
+  #
+  # === Attribute Methods
+  #
+  # All mappers have the ability to read and write values via method calls:
+  #
+  #   mapper.read[:first_name] # => John
+  #   mapper.first_name # => 'John'
+  #   mapper.last_name = 'Smith'
+  class Mapper < BaseMapper
+    extend ActiveSupport::Autoload
+
+    autoload :Targeting
+    autoload :Skipping
+
+    include Targeting
+    include Skipping
+
+    attr_reader :target
+
+    delegate :logger, :to => :target
+
+    # 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 Targeting::NoTargetError.new(self.class) unless target.present?
+
+      @target, @traits = target, traits
+
+      if block_given?
+        singleton_class.trait :extension, &Proc.new
+      end
+    end
+  end
+end