HornsAndHooves-flat_map 0.2.0

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

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

@@ -0,0 +1,15 @@
+module FlatMap
+  module Mapping::Reader
+    # Proc reader accepts a lambda and calls it with the target
+    # as an argument for reading.
+    class Proc < Method
+      # Call a <tt>@method</tt>, which is a {Proc} object,
+      # passing the +target+ object to it.
+      #
+      # @return [Object] value returned by reader's lambda
+      def read
+        @method.call(target)
+      end
+    end
+  end
+end

data/lib/flat_map/mapping/writer.rb

@@ -0,0 +1,11 @@
+module FlatMap
+  # Writer module hosts various writer classes that are used
+  # by mappings to assign values to the target of an associated mapper.
+  module Mapping::Writer
+    extend ActiveSupport::Autoload
+
+    autoload :Basic
+    autoload :Method
+    autoload :Proc
+  end
+end

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

@@ -0,0 +1,25 @@
+module FlatMap
+  module Mapping::Writer
+    # Basic writer simply calls the target's attribute assignment method
+    # passing to it the value being written.
+    class Basic
+      attr_reader :mapping
+
+      delegate :target, :target_attribute, :to => :mapping
+
+      # Initialize writer by passing +mapping+ to it.
+      def initialize(mapping)
+        @mapping = mapping
+      end
+
+      # Call the assignment method of the target, passing
+      # the +value+ to it.
+      #
+      # @param [Object] value
+      # @return [Object] result of assignment
+      def write(value)
+        target.send("#{target_attribute}=", value)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module FlatMap
+  module Mapping::Writer
+    # Method writer calls a method defined by mapper and sends mapping
+    # and value to it as arguments.
+    #
+    # Note that this doesn't set anything on the target itself.
+    class Method < Basic
+      delegate :mapper, :to => :mapping
+
+      # Initialize the writer with a +mapping+ and +method+ name
+      # that should be called on the mapping's mapper.
+      #
+      # @param [FlatMap::Mapping] mapping
+      # @param [Symbol] method
+      def initialize(mapping, method)
+        @mapping, @method = mapping, method
+      end
+
+      # Write a +value+ by sending it, along with the mapping itself.
+      #
+      # @param [Object] value
+      # @return [Object] result of writing
+      def write(value)
+        mapper.send(@method, mapping, value)
+      end
+    end
+  end
+end

data/lib/flat_map/mapping/writer/proc.rb

@@ -0,0 +1,18 @@
+module FlatMap
+  module Mapping::Writer
+    # Proc writer calls a lambda passed on the mapping definition and
+    # sends the mapper's target and value to it.
+    #
+    # Note that this doesn't set anything on the target itself.
+    class Proc < Method
+      # Call a <tt>@method</tt>, which is a +Proc+ object,
+      # passing it the mapping's +target+ and +value+.
+      #
+      # @param [Object] value
+      # @return [Object] result of writing
+      def write(value)
+        @method.call(target, value)
+      end
+    end
+  end
+end

data/lib/flat_map/model_mapper.rb

@@ -0,0 +1,195 @@
+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>:mapper_class_name</tt>] Alternate string form of class name instead of mapper_class.
+  # [<tt>:target</tt>] Allows to manually specify target for the new mapper. May be an object 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 ModelMapper < OpenMapper
+    extend ActiveSupport::Autoload
+
+    autoload :Persistence
+    autoload :Skipping
+
+    include Persistence
+    include Skipping
+
+    delegate :logger, :to => :target
+  end
+end