data_translation 1.1.0

data/CHANGELOG

@@ -0,0 +1,10 @@
+Version 1.1 (2011-04-28)
+
+* Switched order of source checking so that hashes are checked prior to source
+* Changed #from_source to call processor with different arugments depending 
+  upon processor arity
+
+        
+Version 1.0 (2010-07-28)
+
+* Created initial library.

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Scott Patterson
+
+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

@@ -0,0 +1,5 @@
+Provides a means to write data translation maps in Ruby and translate from a source object
+to a hash. A mixin is also provided to help ease the creation of new objects from
+mappings.
+
+See DataTranslation and DataTranslation::Destination for details and examples.

data/lib/data_translation.rb

@@ -0,0 +1,268 @@
+# Simple class to provide an easy way to map and transform data.
+#
+# ==Example Usage
+#
+# agent = DataTranslation.new do |m|
+#   m.option :strict, true
+#
+#   m.set  'source_id', 1
+#
+#   m.link 'login', 'Username'
+#   m.link 'first_name', 'FirstName'
+#   m.link 'last_name', 'LastName'
+#   m.link 'phone_number', lambda {|source| "(#{source['Area']}) #{source['Phone']}"}
+#
+#   m.processor do |values|
+#     Agent.find_or_create_by_source_id_and_login(values['source_id'], values['login'])
+#   end
+# end
+#
+# source = {'Username'  => 'spatterson',
+#           'FirstName' => 'Scott',
+#           'LastName'  => 'Patterson',
+#           'Area'      => '123',
+#           'Phone'     => '456-7890'}
+#
+# results = agent.transform(source)
+#
+# puts results.inspect  # => {"phone_number" => "(123) 456-7890",
+#                       #     "last_name"    => "Patterson",
+#                       #     "login"        => "spatterson",
+#                       #     "first_name"   => "Scott"
+#                       #     "source_id"    => 1}
+#
+# new_object = agent.from_source(source)
+
+class DataTranslation
+  VERSION = '1.1.0'
+
+  attr_reader :mappings, :static_values, :options
+
+  # Includes DataTranslation::Destination in the specified class (klass). If a name
+  # is given, yields and returns a DataTranslation for that name. i.e.
+  # DataTranslation.destination(PlainClass, :source_name) {|dtm| dtm.link ...}
+  def self.destination(klass, name = nil)
+    # No need to include ourself again if we've already extended the class
+    klass.class_eval("include(Destination)") unless klass.include?(Destination)
+
+    if name
+      klass.data_translation_map(name) {|dtm| yield dtm} if block_given?
+      klass.data_translation_map(name)
+    end
+  end
+
+  # Constructor, yields self to allow for block-based configuration.
+  #   Defaults: strict = true
+  def initialize # yields self
+    @mappings      = {}
+    @static_values = {}
+    @options       = {:strict => true}
+    @processor     = nil
+
+    yield self if block_given?
+  end
+
+  # Sets the option with name to value.
+  # Current options are:
+  #   :strict = boolean; true will raise a NonresponsiveSource exception if the source
+  #                      object does not respond to a mapping.
+  #                      false ignores non-existant fields in the source object.
+  def option(name, value)
+    @options[name.to_sym] = value
+  end
+
+  # Sets a specified to field to value during transformation without regard to the source object.
+  # If you wish to link to source object data or use a lambda/block, use #link instead.
+  # to may be any object that can be stored as a Hash key.
+  #
+  # set :field_name, 'Static value'
+  def set(to, value)
+    @static_values[to] = value
+  end
+
+  # Links a destination field to a source method, element, or lambda.
+  # to may be a string, symbol, or any object that can be used as a hash key.
+  # If from is a lambda, called with one argument (the source passed to #transform).
+  # Alternatively, can be called with a block instead of a lambda or from.
+  #
+  # link 'field_name', 'FieldName'
+  # link :field_name, 'FieldName'
+  # link :field_name, lambda {|source| source...}
+  # link(:field_name) {|source| source...}
+  def link(to, from = nil, &block)
+    @mappings[to] = block.nil? ? from : block
+  end
+
+  # If called without a block, returns the current block. If called with a block,
+  # sets the block that will be run with the results from #transform when #from_source
+  # is called. The results of the transformation will be passed if the block
+  # expects only one parameter. If the block expects two parameters both the results
+  # and the original source object will be provided.
+  def processor(&block) # |transform_results [, source_data]|
+    if block_given?
+      @processor = block
+    else
+      @processor
+    end
+  end
+
+  # Removes the currently defined processor, if any.
+  def remove_processor
+    @processor = nil
+  end
+
+  # Given a source object, returns a new hash with elements as determined by the
+  # current mapping. Mapping is set by one or more calls to #link. Options passed
+  # to this method override the instance options. See #option for a list of options.
+  # #link values will override #set values.
+  def transform(source, options = {})
+    options = @options.merge(options)
+
+    apply_static_values(options).merge(apply_mappings(source, options))
+  end
+
+  # Given a source object, returns the results of #transform if no processor is defined
+  # or the results of calling the processor block as defined by #processor.
+  def from_source(source, options = {})
+    results = transform(source, options)
+
+    if @processor
+      if @processor.arity == 1
+        @processor.call(results)
+      else
+        @processor.call(results, source)
+      end
+    else
+      results
+    end
+  end
+
+  # Yields the mapping object so that options and links can be applied within a block.
+  def update # yields self
+    yield self
+  end
+
+  private
+
+    # Given a source object and optional options hash, iterates over the current mappings
+    # (defined by #link) and returns a Hash of results.
+    def apply_mappings(source, options = {})
+      results = {}
+
+      @mappings.each do |to, from|
+        if from.respond_to? :call                # Lambda
+          results[to] = from.call(source)
+        elsif source.respond_to?(:[]) &&         # Hash-like Object
+              (options[:strict] == false || source.has_key?(from))
+          results[to] = source[from]
+        elsif source.respond_to?(from.to_sym)    # Source Object
+          results[to] = source.send(from.to_sym)
+        else
+          raise NonresponsiveSource,
+                "#{to}: #{source.class} does not respond to '#{from}' (#{from.class})"
+        end
+      end
+
+      results
+    end
+
+    # Returns a hash of static values as defined by the #set method.
+    def apply_static_values(options = {})
+      @static_values # currently nothing to do to process, so we just pass it along for now.
+    end
+
+  ## Mixins ##
+
+  # Provides helper methods for mapping and creating new objects from source data.
+  #
+  # In addition to including the mixin DataTranslation::Destination, a class method
+  # called initialize_from_data_translation may optionally be provided that takes a hash
+  # of translated data. If not present, the from_source will pass a hash of the
+  # transformation results to the new method.
+  #
+  # Multiple mappings may be given for a single destination by using different names
+  # for them. e.g. :source1 and :source2 as names yield different mappings.
+  #
+  # ==Example Usage
+  #
+  # class DestinationObject
+  #   include DataTranslation::Destination
+  #
+  #   def self.initialize_from_data_translation(results)
+  #   end
+  # end
+  #
+  # DestinationObject.data_translation_map(:source_name) do |dtm|
+  #   dtm.link 'first_key', 'Key1'
+  # end
+  #
+  # source = {'Key1' => 'Value1'}
+  #
+  # new_object = DestinationObject.from_source(:source_name, source)
+
+  module Destination
+    # Provides our class methods when included.
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Given the name of a mapping and a source object, transforms the source object
+      # based upon the specified mapping and attempts to process the results using one of
+      # several methods that are checked in the following order:
+      # *  DataTranslation#processor defined block
+      # *  Destination class initialize_from_data_translation
+      # *  Destination class default constructor
+      # with the resulting hash if that method is not defined.
+      # Returns an instance of the class based upon the source data.
+      def from_source(name, source)
+        dtm = data_translation_map(name)
+
+        if dtm.processor
+          dtm.from_source(source)
+        elsif respond_to?(:initialize_from_data_translation)
+          initialize_from_data_translation(dtm.transform(source))
+        else
+          new(dtm.transform(source))
+        end
+      end
+
+      # Given the name of a mapping, returns the existing mapping with that name
+      # or creates one with that name and yields it if a block is given.
+      # Returns the DataTranslation mapping for the specified name.
+      def data_translation_map(name) # yields DataTranslation
+        @dt_mappings       ||= {}
+        @dt_mappings[name] ||= DataTranslation.new
+
+        yield @dt_mappings[name] if block_given?
+
+        @dt_mappings[name]
+      end
+
+      # Returns a string containing a sample DataTranslation mapping for this instance
+      # based upon actual column names (assuming this is an ActiveRecord class or
+      # another class that provides an array of string column/attribute names via a
+      # column_names class method).
+      #
+      # Passing the name argument sets it as the translation name in the output.
+      def stub_data_translation_from_column_names(name = 'name')
+        map = ["DataTranslation.destination(#{self}, :#{name}) do |dtm|"]
+
+        column_names.each do |col|
+          map << "\tdtm.link :#{col}, :#{col}"
+        end
+
+        map << "end"
+
+        map.join("\n")
+      end
+    end
+  end
+
+
+  ## Exceptions ##
+
+  # Raised when the source object does not respond to the from link.
+  class NonresponsiveSource < Exception
+  end
+end

data/test/tc_data_translation.rb

@@ -0,0 +1,159 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'test/unit'
+require 'mocha'
+require 'data_translation'
+
+class TC_DataTranslation < Test::Unit::TestCase
+  def test_should_set_options
+    dt = DataTranslation.new do |m|
+      m.option :strict, true
+    end
+
+    assert_equal true, dt.options[:strict]
+  end
+
+  def test_should_link_string_key
+    dt = DataTranslation.new do |m|
+      m.link 'To', 'From'
+    end
+
+    assert_equal 'From', dt.mappings['To']
+  end
+
+  def test_should_link_to_lambda
+    dt = DataTranslation.new do |m|
+      m.link 'To', lambda {|source| 'Lambda'}
+    end
+
+    assert_equal 'Lambda', dt.mappings['To'].call({})
+  end
+
+  def test_should_link_to_block
+    dt = DataTranslation.new do |m|
+      m.link('To') {|source| 'Block'}
+    end
+
+    assert_equal 'Block', dt.mappings['To'].call({})
+  end
+
+  def test_should_set_static_value
+    dt = DataTranslation.new do |m|
+      m.set 'To', 'StaticFrom'
+    end
+
+    assert_equal 'StaticFrom', dt.static_values['To']
+  end
+
+  def test_should_transform_with_lambda
+    dt = DataTranslation.new do |m|
+      m.link 'Phone', lambda {|source| "(#{source['Area']}) #{source['PhoneNumber']}"}
+    end
+
+    source = {'Area' => 123, 'PhoneNumber' => '456-7890'}
+
+    assert_equal '(123) 456-7890', dt.transform(source)['Phone']
+  end
+
+  def test_should_transform_with_block
+    dt = DataTranslation.new do |m|
+      m.link('Phone') {|source| "(#{source['Area']}) #{source['PhoneNumber']}"}
+    end
+
+    source = {'Area' => 123, 'PhoneNumber' => '456-7890'}
+
+    assert_equal '(123) 456-7890', dt.transform(source)['Phone']
+  end
+
+  def test_should_transform_hash_source
+    source = {'Key1' => 'Value1', 'Key2' => 'Value2'}
+
+    dt = DataTranslation.new do |m|
+      m.link 'Dest1', 'Key1'
+      m.link 'Dest2', 'Key2'
+    end
+
+    results = dt.transform(source)
+
+    assert_equal 'Value1', results['Dest1']
+    assert_equal 'Value2', results['Dest2']
+  end
+
+  def test_should_transform_object_source
+    source = mock('Key1' => 'Value1', 'Key2' => 'Value2')
+
+    dt = DataTranslation.new do |m|
+      m.link 'Dest1', 'Key1'
+      m.link 'Dest2', 'Key2'
+    end
+
+    results = dt.transform(source)
+
+    assert_equal 'Value1', results['Dest1']
+    assert_equal 'Value2', results['Dest2']
+  end
+
+  # Ran into an issue when mapping US address data from a hash with
+  # symbol keys. :zip was specified as a key, but because we checked
+  # for object methods first, enumerable#zip was being called instead
+  # of hash#[].
+  def test_should_check_for_hashlike_object_before_source
+    source = {:zip => '99999'}
+
+    dt = DataTranslation.new do |m|
+      m.link 'ZipCode', :zip
+    end
+
+    source.expects(:zip).never
+
+    results = dt.transform(source)
+
+    assert_equal '99999', results['ZipCode']
+  end
+
+  def test_should_call_processor_on_transform
+    dt = DataTranslation.new do |m|
+      m.link :name, 'Name'
+
+      m.processor do |results|
+        "Construct called with #{results[:name]}"
+      end
+    end
+
+    assert_equal 'Construct called with value', dt.from_source({'Name' => 'value'})
+  end
+
+  def test_should_raise_exception_when_strict
+    source = {}
+
+    dt = DataTranslation.new {|m| m.link 'Key1', 'Value1'}
+
+    assert_raises(DataTranslation::NonresponsiveSource) do
+      dt.transform(source)
+    end
+  end
+
+  def test_should_transform_with_static_value
+    dt = DataTranslation.new {|m| m.set 'To', 'StaticValue'}
+
+    assert_equal({'To' => 'StaticValue'}, dt.transform({}))
+  end
+
+  def test_should_not_raise_exception_when_not_strict
+    source = {}
+
+    dt = DataTranslation.new {|m| m.link 'Key1', 'Value1'}
+
+    assert_nothing_raised do
+      dt.transform(source, :strict => false)
+    end
+  end
+
+  def test_should_update_dt
+    dt = DataTranslation.new {|m| m.option :strict, true}
+    assert dt.options[:strict]
+
+    dt.update {|m| m.option :strict, false}
+    assert ! dt.options[:strict]
+  end
+end

data/test/tc_data_translation_destination.rb

@@ -0,0 +1,124 @@
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'test/unit'
+require 'mocha'
+require 'data_translation'
+
+## Test Objects
+
+class TestObject
+  include DataTranslation::Destination
+
+  attr_reader :name, :options
+
+  def self.initialize_from_data_translation(params)
+    TestObject.new(params.delete('name'), params)
+  end
+
+  def initialize(name, options = {})
+    @name    = name
+    @options = options
+  end
+
+  def self.column_names
+    ['id', 'first_name', 'last_name']
+  end
+end
+
+class PlainObject
+  attr_reader :options
+
+  def initialize(options)
+    @options = options
+  end
+end
+
+
+class TC_DataTranslationDestination < Test::Unit::TestCase
+  def setup
+    @source = {'Name' => 'test object', 'Key1' => 'Value1', 'Key2' => 'Value2'}
+  end
+
+  def test_should_create_map(klass = TestObject)
+    klass.data_translation_map(:hash_source) do |m|
+      m.option :strict, true
+
+      m.link 'name',       'Name'
+      m.link 'first_key',  'Key1'
+      m.link 'second_key', 'Key2'
+
+      m.remove_processor
+      yield m if block_given?
+    end
+
+    assert klass.data_translation_map(:hash_source).options[:strict]
+    assert_equal 'Name', klass.data_translation_map(:hash_source).mappings['name']
+    assert_equal 'Key1', klass.data_translation_map(:hash_source).mappings['first_key']
+    assert_equal 'Key2', klass.data_translation_map(:hash_source).mappings['second_key']
+  end
+
+  def test_should_create_new_object_using_custom_constructor
+    test_should_create_map
+
+    to = TestObject.from_source(:hash_source, @source)
+
+    assert_equal 'test object', to.name
+    assert_equal 'Value1', to.options['first_key']
+    assert_equal 'Value2', to.options['second_key']
+  end
+
+  def test_should_create_new_object_using_default_constructor
+    DataTranslation.destination(PlainObject)
+    test_should_create_map(PlainObject)
+
+    to = PlainObject.from_source(:hash_source, @source)
+
+    assert_equal 'test object', to.options['name']
+    assert_equal 'Value1', to.options['first_key']
+    assert_equal 'Value2', to.options['second_key']
+  end
+
+  def test_should_call_processor_if_given
+    DataTranslation.destination(PlainObject)
+    test_should_create_map(PlainObject) do |m|
+      m.processor do |results, source|
+        results.values.sort # for consistency we sort our values
+      end
+    end
+
+    assert_equal ['Value1', 'Value2', 'test object'],
+                 PlainObject.from_source(:hash_source, @source)
+  end
+
+  def test_should_return_mapping_for_name
+    test_should_create_map
+
+    assert TestObject.data_translation_map(:hash_source).kind_of?(DataTranslation)
+  end
+
+  def test_should_make_class_destination
+    DataTranslation.destination(PlainObject)
+
+    assert PlainObject.include?(DataTranslation::Destination)
+  end
+
+  def test_should_make_class_destination_and_yield
+    DataTranslation.destination(PlainObject, :hash_source) do |dtm|
+      dtm.link 'first_key', 'Key1'
+    end
+
+    assert_equal 'Key1', PlainObject.data_translation_map(:hash_source).mappings['first_key']
+    assert PlainObject.respond_to?(:from_source)
+  end
+
+  def test_should_stub_map_from_column_names
+    assert_equal "DataTranslation.destination(TestObject, :my_name) do |dtm|\n\tdtm.link :id, :id\n\tdtm.link :first_name, :first_name\n\tdtm.link :last_name, :last_name\nend",
+                 TestObject.stub_data_translation_from_column_names(:my_name)
+  end
+
+  def test_should_not_include_destination_multiple_times
+    DataTranslation::Destination.expects(:included).never
+
+    DataTranslation.destination(TestObject)
+  end
+end

data/test/ts_all.rb

@@ -0,0 +1,4 @@
+$:.unshift(File.dirname(__FILE__))
+
+require 'tc_data_translation'
+require 'tc_data_translation_destination'

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: data_translation
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: 
+  segments: 
+  - 1
+  - 1
+  - 0
+  version: 1.1.0
+platform: ruby
+authors: 
+- Scott Patterson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-28 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Provides a means to write data translation maps in Ruby and transform data from a source object.
+email: scott.patterson@digitalaun.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+- CHANGELOG
+files: 
+- lib/data_translation.rb
+- test/tc_data_translation.rb
+- test/tc_data_translation_destination.rb
+- test/ts_all.rb
+- README
+- LICENSE
+- CHANGELOG
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: Generic data mapping and translation expressed in Ruby.
+test_files: 
+- test/ts_all.rb