HornsAndHooves-flat_map 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e476b0c2831807b9734932bcec75f3d798a09d08
+  data.tar.gz: 88d957bf1d9467c8abcf2f1e75e655c28630a51c
+SHA512:
+  metadata.gz: 6d721973e3a24a1f9e42599f7daaa3ce4c8ca34b7de8cbdcd8cec93249a72ef4adbe29025ddf481a52de4622309dd04aa2d1cd8f89028cb426001cfa5f449b9f
+  data.tar.gz: f8b5c8efcdff94145f7a329abc3f124797754bcc50baf3ecd828d70cd9bb37973f8a247e4fb4d99b7fcc1b4ea14a61da4d808b30c923d40b032ad5641bee688a

data/.gitignore

@@ -0,0 +1,34 @@
+# SimpleCov generated
+coverage
+coverage.data
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# IDE
+.idea
+
+# 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 documentation
+--order rand
+--profile

data/.ruby-gemset

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

data/.ruby-version

@@ -0,0 +1 @@
+2.1.2

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/HornsAndHooves-flat_map.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "flat_map/version"
+
+Gem::Specification.new do |s|
+  s.name        = "HornsAndHooves-flat_map"
+  s.version     = FlatMap::VERSION
+  s.authors     = ["Artem Kuzko", "Zachary Belzer", "Sergey Potapov"]
+  s.email       = ["a.kuzko@gmail.com", "zbelzer@gmail.com", "blake131313@gmail.com"]
+  s.homepage    = "https://github.com/HornsAndHooves/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.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>, ["~> 4.0.5"])
+  s.add_dependency(%q<activerecord>, ["~> 4.0.5"])
+  s.add_dependency(%q<yard>, [">= 0"])
+
+  s.add_development_dependency "rspec", "~> 3.0"
+  s.add_development_dependency "rspec-its"
+  s.add_development_dependency "rake"
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 HornsAndHooves
+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,214 @@
+# FlatMap
+
+[![Build Status](https://secure.travis-ci.org/HornsAndHooves/flat_map.png)](http://travis-ci.org/HornsAndHooves/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.
+* `:mapper_class_name` Alternate string form of class name instead of mapper_class.
+* `: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) 2014 HornsAndHooves.
+
+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/lib/flat_map.rb

@@ -0,0 +1,14 @@
+require 'ostruct'
+require 'active_support'
+require 'active_record'
+
+require "flat_map/version"
+require 'flat_map/mapping'
+require 'flat_map/errors'
+require 'flat_map/open_mapper'
+require 'flat_map/model_mapper'
+
+module FlatMap
+  # for backwards compatability
+  Mapper = ModelMapper
+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