flat_map 0.0.3

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NjNmMzU5MGI0NjIwZGQyZmY4YzBlM2RhYzFmYTMzNGJmM2ZiMzIzMA==
+  data.tar.gz: !binary |-
+    NjAxZjRjYThiNWMxN2QwN2NkMWNkODFhZDg0NjEzZDQ0MGE5YWM5ZQ==
+SHA512:
+  metadata.gz: !binary |-
+    N2M2NmQzZmFkMjZjMjg3NThmZjhjN2I0YmI2NGMyMWQxZTcyNTYwYTFmNzJj
+    NmM0Yzc1NDg4YWM1MmM1ZGE3ZTA3MTUzZTNmNjgwZGZkZDYxN2ViMzliNDVl
+    NWQ4Yjg3ZDI5NTg2MmZiOTQ2ZjQ5ODk1YTUwODQyN2JmNzIxNDQ=
+  data.tar.gz: !binary |-
+    ZTg1ZmI2NzY1NjA3ZGYyYzQ1NTAwYzFlMDUxODY2Y2M5YmNlMWI5YTNkNWYx
+    MTI5NGQwNDA5YmQwOTNjOTJiYmRhZDdjYWY0YTkwMzU4MzQxM2FlYjU5Nzgy
+    YzlkYmEzNmNlM2ExNTA5M2E5Y2E1OGFlNDViYmU1MGVmYzg5M2U=

data/.gitignore

@@ -0,0 +1,31 @@
+# SimpleCov generated
+coverage
+coverage.data
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkg
+
+*.gem
+Gemfile.lock
+
+# For MacOS:
+.DS_Store
+
+# exclude everything in tmp
+tmp/*
+# except the metric_fu directory
+!tmp/metric_fu/
+# but exclude everything *in* the metric_fu directory
+tmp/metric_fu/*
+# except for the _data directory to track metrical outputs
+!tmp/metric_fu/_data/

data/.metrics

@@ -0,0 +1,17 @@
+MetricFu::Configuration.run do |config|
+  [ :rcov,
+    :rails_best_practices
+  ].each do |metric|
+    config.configure_metric(metric) do |m|
+      m.enabled = false
+    end
+  end
+
+  config.configure_metric(:cane) do |cane|
+    cane.line_length = 100
+  end
+
+  config.configure_metric(:flay) do |flay|
+    flay.minimum_score = 10
+  end
+end

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format nested
+--order rand
+--profile

data/.ruby-gemset

@@ -0,0 +1 @@
+flat_map

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.9.3-p448

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+script: "bundle exec rake spec"
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+notifications:
+  email:
+    - a.kuzko@gmail.com

data/Gemfile

@@ -0,0 +1,20 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in flat_map.gemspec
+gemspec
+
+group :development do
+  gem 'redcarpet'
+  gem 'yard'
+  gem 'pry'
+end
+
+group :development, :test do
+  # code metrics:
+  gem "metric_fu"
+end
+
+group :test do
+  gem 'simplecov'          , :require => false
+  gem 'simplecov-rcov-text', :require => false
+end

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 TMXCredit, authors Artem Kuzko, Zachary Belzer, Sergey Potapov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,211 @@
+# FlatMap
+
+[![Build Status](https://secure.travis-ci.org/TMXCredit/flat_map.png)](http://travis-ci.org/TMXCredit/flat_map)
+
+FlatMap is a flexible tool for mapping a complex, deeply nested object graph
+into a mapper object with all mapped attributes accessible in a plain way.
+
+
+## Usage
+
+### 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:
+
+```ruby
+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:
+
+```ruby
+  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:
+
+* `:format` 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
+* `:reader` 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.
+* `:writer` 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.
+* `:multiparam` 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.
+
+```ruby
+  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:
+
+* `:mapper_class` Specifies mapper class if it cannot be determined from mounting itself
+* `:target` 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:
+            `mount :title, :target => lambda{ |customer| customer.title_customers.build.build_title }`
+* `:traits` Specifies list of traits to be used by mounted mapper
+* `:suffix` 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.
+
+```ruby
+  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:
+
+```ruby
+  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
+
+`FlatMap::Mapper` includes `ActiveModel::Validations` 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 `ActiveModel::Validation`, they already support ActiveSupport's callbacks.
+Additionally, `:save` callbacks have been defined (i.e. there have been define_callbacks `:save`
+call for `FlatMap::Mapper`). This allows you to control flow of mapper saving:
+
+```ruby
+  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
+`skip!` method is called on mapper, it will return `true` for `valid?` and `save`
+method calls without performing any other operations. For example:
+
+```ruby
+  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_product
+        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:
+
+```ruby
+  mapper.read[:first_name] # => John
+  mapper.first_name # => 'John'
+  mapper.last_name = 'Smith'
+```
+
+## Run tests
+
+```sh
+rake spec
+```
+
+## Credits
+
+* [Artem Kuzko](https://github.com/akuzko)
+* [Zachary Belzer](https://github.com/zbelzer)
+* [Potapov Sergey](https://github.com/greyblake)
+
+## Copyright
+
+Copyright (c) 2013 TMX Credit.

data/Rakefile

@@ -0,0 +1,15 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+task :default => :spec
+RSpec::Core::RakeTask.new
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "flat_map #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/flat_map.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "flat_map/version"
+
+Gem::Specification.new do |s|
+  s.name        = "flat_map"
+  s.version     = FlatMap::VERSION
+  s.authors     = ["TMX Credit", "Artem Kuzko", "Zachary Belzer", "Sergey Potapov"]
+  s.email       = ["rubygems@tmxcredit.com", "a.kuzko@gmail.com", "zbelzer@gmail.com", "blake131313@gmail.com"]
+  s.homepage    = "https://github.com/TMXCredit/flat_map"
+  s.licenses    = ["LICENSE"]
+  s.summary     = %q{Deep object graph to a plain properties mapper}
+  s.description = %q{This library allows to map accessors and properties of deeply
+    nested object graph to a plain mapper object with flexible behavior}
+
+  s.rubyforge_project = "flat_map"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  s.add_dependency(%q<activesupport>, ["~> 3.2"])
+  s.add_dependency(%q<activerecord>, ["~> 3.2"])
+  s.add_dependency(%q<yard>, [">= 0"])
+
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "rake"
+end

data/lib/flat_map.rb

@@ -0,0 +1,9 @@
+require 'active_support/core_ext'
+require 'active_record'
+
+require "flat_map/version"
+require 'flat_map/mapping'
+require 'flat_map/errors'
+require 'flat_map/base_mapper'
+require 'flat_map/mapper'
+require 'flat_map/empty_mapper'

data/lib/flat_map/base_mapper.rb

@@ -0,0 +1,95 @@
+module FlatMap
+  # +BaseMapper+ is an abstract class that hosts overwhelming majority
+  # of common functionality of {EmptyMapper EmptyMappers} and {Mapper Mappers}.
+  #
+  # For more detailed information on what mappers are, refer to {Mapper} documentation.
+  class BaseMapper
+    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_reader :traits
+    attr_writer :host, :suffix
+    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
+
+    # Raise exception on trying to initialize an instance.
+    #
+    # @raise [RuntimeError]
+    def initialize
+      raise 'BaseMapper is abstract class and cannot be initialized'
+    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