matterful_attributes 0.0.3 → 0.0.6

data/.gitignore

@@ -1,32 +1,32 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-*.sassc
-.sass-cache
-capybara-*.html
-.rspec
-/.bundle
-/vendor/bundle
-/log/*
-/tmp/*
-/db/*.sqlite3
-/public/system/*
-/coverage/
-/spec/tmp/*
-**.orig
-rerun.txt
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.sassc
+.sass-cache
+capybara-*.html
+.rspec
+/.bundle
+/vendor/bundle
+/log/*
+/tmp/*
+/db/*.sqlite3
+/public/system/*
+/coverage/
+/spec/tmp/*
+**.orig
+rerun.txt
 pickle-email-*.html

data/Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in matterful_attributes.gemspec
-gemspec
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in matterful_attributes.gemspec
+gemspec

data/LICENSE.txt

@@ -1,22 +1,22 @@
-Copyright (c) 2013 Nick Gorbikoff
-
-MIT License
-
-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.
+Copyright (c) 2013 Nick Gorbikoff
+
+MIT License
+
+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.md

@@ -1,27 +1,137 @@
-matterful_attributes
-====================
-
-Ruby / Rails gem that shims ActiveRecord::Base to provide some helpful methods for parsing out attributes that matter to humans, i.e.
-``` Address.first.matterful_attributes ```
-will return a hash of attributes minus
-<b> id, type, polymorphic_id, polymorphic_type, cretated_at, updated_at</b> and can also skip all foreign_keys, like <b>category_id or status_id </b>.
-
-This is really useful when you need to be able to import, compare and update information on a record from an external source like a CSV file or a legacy DB. In that context only attributes specific to the model matter. In the world outside of rails, such as some old legacy DB these Rails specific attributes don't mean much. And I got tired of writing things like
-```ruby
-Address.first.attributes.except('id','created_at','updated_at').diff(OldStyleAddress.first.attributes)
-```
-It's much cleaner to right it this way:
-```ruby
-Address.first.matterful_diff(OldStyleAddress.first)
-```
-don't  you think?
-
-
-Production
-==========
-This was extracted from production code that's tested. However use at your own risk. NO warranties or guarantees provided!
-
-
-Tests
-=====
-This gem needs tests! It's tested in the context of my production code, but no gem specific tests. I'll add them later if time allows. Really bad practice, I know, but I'm really short on time.
+matterful_attributes
+====================
+
+Ruby / Rails gem that shims ActiveRecord::Base to provide some helpful methods for parsing out attributes that matter to humans, i.e.
+``` Address.first.matterful_attributes ```
+will return a hash of attributes minus
+<b> id, type, polymorphic_id, polymorphic_type, cretated_at, updated_at</b> and can also skip all foreign_keys, like <b>category_id or status_id </b>.
+
+This is really useful when you need to be able to import, compare and update information on a record from an external source like a CSV file or a legacy DB. In that context only attributes specific to the model matter. In the world outside of rails, such as some old legacy DB these Rails specific attributes don't mean much. And I got tired of writing things like
+```ruby
+Address.first.attributes.except('id','created_at','updated_at').diff(OldStyleAddress.first.attributes)
+```
+It's much cleaner to right it this way:
+```ruby
+Address.first.matterful_diff(OldStyleAddress.first)
+```
+don't  you think?
+
+
+Production
+==========
+This was extracted from production code that's tested. However use at your own risk. NO warranties or guarantees provided!
+
+
+Tests
+=====
+This gem needs tests! It's tested in the context of my production code, but no gem specific tests. I'll add them later if time allows. Really bad practice, I know, but I'm really short on time.
+I suggest you check out this answer on stackoverflow: http://stackoverflow.com/a/13156750/198424
+
+Usage
+=====
+Using Gemfile:
+
+```ruby
+gem 'matterful_attributes', require: 'matterful_attributes'
+```
+
+Available methods
+```ruby
+# List attributes that matter to humans
+matterful_attributes( source,
+                      optons={ default:true,
+                               sti: true,
+                               polymorphic: true,
+                               foreign_key: true,
+                               extra: ['Array', 'of extra', 'attributes', 'to ignore as strings']
+                             })
+
+# Do comparison of two similar Records for attributes that matter. Returns a
+# hash of attributes that will be updated with the information that will update it
+matterful_diff(source ,
+                optons={ default:true,
+                               sti: true,
+                               polymorphic: true,
+                               foreign_key: true,
+                               extra: ['Array', 'of extra', 'attributes', 'to ignore as strings']
+                             })
+
+# Diff and update target from source. Returns self. with updated attributes, but doesn't save!!!
+matterful_update(source, options={ default:true,
+                               sti: true,
+                               polymorphic: true,
+                               foreign_key: true,
+                               extra: ['Array', 'of extra', 'attributes', 'to ignore as strings']
+                             })
+
+# Same as matterful_update but also saves self. right away if valid. Returns true / false.
+matterful_update!(source, options={ default:true,
+                               sti: true,
+                               polymorphic: true,
+                               foreign_key: true,
+                               extra: ['Array', 'of extra', 'attributes', 'to ignore as strings']
+                             })
+
+# I decided not to overload standard comparison operators to avoid confusion. hence this. Returns true or false
+same_as?(source, options={ default:true,
+                               sti: true,
+                               polymorphic: true,
+                               foreign_key: true,
+                               extra: ['Array', 'of extra', 'attributes', 'to ignore as strings']
+                             })
+```
+
+!!! Attention
+Foreign_keys such as category_id are by default not ignored pass foreign_key: false to ignore them. See example below.
+
+
+Now all your models have matterful INSTANCE methods. These methods only make sence to use in an instance of Address.first, no in Address  as class by itself doesn't hod any information that matters to humans: sucha s when you import CSV data you are going to update a very specific record, not some abstract Address.
+
+```ruby
+# Assuming you have an Address model like so
+class Address < ActiveRecord::Base {
+                  :id => :integer,
+      :address_line_1 => :string,
+      :address_line_2 => :string,
+      :address_line_3 => :string,
+                :city => :string,
+               :state => :string,
+                 :zip => :string,
+             :country => :string,
+                :attn => :string,
+         :category_id => :integer,
+      :addressable_id => :integer,
+    :addressable_type => :string,
+          :created_at => :datetime,
+          :updated_at => :datetime
+}
+```
+
+```ruby
+# List matterful attributes, without foreign_keys like category_id
+Address.first.matterful_attributes(foreign_keys: false)
+
+# Returns hash like so
+# {"address_line_1"=>"300 Sample Drive",
+# "address_line_2"=>nil,
+# "address_line_3"=>nil,
+# "city"=>"Buffalo Grove",
+# "state"=>"IL",
+# "zip"=>"60089",
+# "country"=>"USA",
+# "attn"=>nil}
+
+# List matterful attributes, without foreign_keys like category_id
+Address.first.matterful_diff(Address.last)
+
+# Returns hash like so
+# {"address_line_1"=>"300 Sample Drive",
+# "address_line_2"=>nil,
+# "address_line_3"=>nil,
+# "city"=>"Buffalo Grove",
+# "state"=>"IL",
+# "zip"=>"60089",
+# "country"=>"USA",
+# "attn"=>nil}
+
+```

data/Rakefile

@@ -1 +1 @@
-require "bundler/gem_tasks"
+require "bundler/gem_tasks"

data/lib/matterful_attributes.rb

@@ -1,74 +1,92 @@
-require "matterful_attributes/version"
-
-module MatterfulAttributes
-  extend ActiveSupport::Concern
-    # These only make sense as instance methods
-      def matterful_attributes(options={})
-        options = options.dup
-        default     = options[:default].nil?        ? true : options[:default]
-        foreign_key = options[:foreign_key].nil?    ? true : options[:foreign_key]
-        sti         = options[:sti].nil?            ? true : options[:sti]
-        polymorphic = options[:polymorphic].nil?    ? true : options[:polymorphic]
-        # extra keys supplied as array of strings to ignore in comparison
-        attributes_to_ignore = options[:extra].nil? ? []   : options[:extra]
-
-        # Let's check for and add typical attributes that sti & polymorphic models have, override
-        # this by sti: false, polymorphic: false, :foreign_key: false
-        # by default when looking to compare two objects
-        # Customer.find(1).shipping_address.same_as? Address.new(city: 'Chicago')
-        # we really only want to see if any of the 'matterfule information changed', like address_line_1 or city.
-        # TODO: I guess I could do some smart checking on the model to see what kind of attributes it has.
-        # For now we'll just check for all that we want to remove
-        if default
-          attributes_to_ignore += ['id', 'created_at', 'updated_at']
-        end
-        # By default we want foreign keys like caegory_id as they provide useful information about current record.
-        # Let's say you import a bunch of addresses
-        # and they ony matterful change was from shipping to billing category.
-        unless foreign_key
-          # This will skip polymorphic style foreign keys and only deal with belongs_to style keys
-          attributes_to_ignore += attributes.keys.keep_if{|k| k.match(/_id\z/) && !k.match(/able_id\z/) }
-        end
-        if sti
-          attributes_to_ignore += ['type']
-        end
-        # If you are looking at a model that is polymorphic than most like you want to update something
-        # like city for an Address , not addressable_id or addresable_type
-        # That is more likely type of information to be updated on external import.
-        if polymorphic
-          attributes_to_ignore += attributes.keys.keep_if{|k| k.match(/able_id\z/) }
-          attributes_to_ignore += attributes.keys.keep_if{|k| k.match(/able_type\z/) }
-        end
-        attributes.except(*attributes_to_ignore)
-      end
-
-      def same_as?(source,options={})
-        matterful_attributes(options) == source.matterful_attributes(options)
-      end
-
-      def matterful_diff(source,options={})
-        matterful_attributes(options).diff(source.matterful_attributes(options))
-      end
-
-      # Update self if source object has new data but DO NOT save. Let's say you want to do
-      # futer processing on the new data. Validation, upcasing, concatination
-      def matterful_update(source,options={})
-        # Pay attention to this! Reversing comparison to get expected results
-        if !(target_attributes = source.matterful_diff(self, options={})).empty?
-          target_attributes.each_pair do |k,v|
-            self[k] = v
-          end
-        end
-        self
-      end
-
-      def matterful_update!(source,options={})
-        # This will update self and save self if valid. Will return true or false.
-        self.matterful_update(source,options={})
-        save
-      end
-end
-
-# include the extension
-ActiveRecord::Base.send(:include, MatterfulAttributes)
-
+require "matterful_attributes/version"
+
+module MatterfulAttributes
+  extend ActiveSupport::Concern
+    # These only make sense as instance methods
+      def matterful_attributes(options={})
+        options = options.dup
+        default     = options[:default].nil?        ? true : options[:default]
+        foreign_key = options[:foreign_key].nil?    ? true : options[:foreign_key]
+        sti         = options[:sti].nil?            ? true : options[:sti]
+        polymorphic = options[:polymorphic].nil?    ? true : options[:polymorphic]
+        # Set compare_blank_values to false only if you, DO NOT want to update existing information with nil information from the new object
+        # For example, sometimes your table has historical data, while source, may only have current. You may want to keep historical data
+        # for reference, or if some process relies on it. It's generally not a good idea to delete good data, unless you have to.
+        compare_blank_values = options[:compare_blank_values].nil?  ? true : options[:compare_blank_values]
+
+        # extra keys supplied as array of strings to ignore in comparison
+        attributes_to_ignore = options[:extra].nil? ? []   : options[:extra]
+
+        # Let's check for and add typical attributes that sti & polymorphic models have, override
+        # this by sti: false, polymorphic: false, foreign_key: false
+        # by default when looking to compare two objects
+        # Customer.find(1).shipping_address.same_as? Address.new(city: 'Chicago')
+        # we really only want to see if any of the 'matterfule information changed', like address_line_1 or city.
+        # TODO: I guess I could do some smart checking on the model to see what kind of attributes it has.
+        # For now we'll just check for all that we want to remove
+        if default
+          attributes_to_ignore += ['id', 'created_at', 'updated_at']
+        end
+        # By default we want foreign keys like caegory_id as they provide useful information about current record.
+        # Let's say you import a bunch of addresses
+        # and they ony matterful change was from shipping to billing category.
+        unless foreign_key
+          # This will skip polymorphic style foreign keys and only deal with belongs_to style keys
+          attributes_to_ignore += attributes.keys.keep_if{|k| k.match(/_id\z/) && !k.match(/able_id\z/) }
+        end
+        if sti
+          attributes_to_ignore += ['type']
+        end
+        # If you are looking at a model that is polymorphic than most like you want to update something
+        # like city for an Address , not addressable_id or addresable_type
+        # That is more likely type of information to be updated on external import.
+        if polymorphic
+          attributes_to_ignore += attributes.keys.keep_if{|k| k.match(/able_id\z/) }
+          attributes_to_ignore += attributes.keys.keep_if{|k| k.match(/able_type\z/) }
+        end
+
+        # This will only be invoked on blank values
+        # Since this gem is used only in the context of ActiveRecord, safe to use blank?, from ActionPack
+        # KEEP IN MIND THIS THI WILL NOT CHECK for blanks in sti, foreign, and default attributes
+        # it will only check for blank values in keys not in attributes_to_ignore already!!!!
+        unless compare_blank_values
+          attributes.except(*attributes_to_ignore).keys.each do |key|
+            if self.send(key).blank?
+              attributes_to_ignore += [key]
+            end
+          end
+        end
+        attributes.except(*attributes_to_ignore)
+      end
+
+      def same_as?(source,options={})
+        matterful_attributes(options) == source.matterful_attributes(options)
+      end
+
+      def matterful_diff(source,options={})
+        matterful_attributes(options).diff(source.matterful_attributes(options))
+      end
+
+      # Update self if source object has new data but DO NOT save. Let's say you want to do
+      # futer processing on the new data. Validation, upcasing, concatination
+      def matterful_update(source,options={})
+        options = options.dup
+        # Pay attention to this! Reversing comparison to get expected results
+        if !(target_attributes = source.matterful_diff(self, options)).empty?
+          target_attributes.each_pair do |k,v|
+            self[k] = v
+          end
+        end
+        self
+      end
+
+      def matterful_update!(source,options={})
+        # This will update self and save self if valid. Will return true or false.
+        self.matterful_update(source,options)
+        save
+      end
+end
+
+# include the extension
+ActiveRecord::Base.send(:include, MatterfulAttributes)
+

data/lib/matterful_attributes/version.rb

@@ -1,3 +1,3 @@
-module MatterfulAttributes
-  VERSION = "0.0.3"
-end
+module MatterfulAttributes
+  VERSION = "0.0.6"
+end

data/matterful_attributes.gemspec

@@ -1,23 +1,23 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'matterful_attributes/version'
-
-Gem::Specification.new do |spec|
-  spec.name          = "matterful_attributes"
-  spec.version       = MatterfulAttributes::VERSION
-  spec.authors       = ["Nick Gorbikoff"]
-  spec.email         = ["nick.gorbikoff@gmail.com"]
-  spec.description   = %q{Ruby / Rails gem that shims ActiveRecord::Base to provide some helpful methods for parsing out attributes that matter to humans, i.e. Address.first.matterful_attributes will return a hash of attributes minus id, type, polymorphic_id, polymorphic_type, cretated_at, updated_at and can also skip all foreign_keys, like category_id or status_id. }
-  spec.summary       = %q{See Readme.md}
-  spec.homepage      = "https://github.com/konung/matterful_attributes"
-  spec.license       = "MIT"
-
-  spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake"
-end
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'matterful_attributes/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "matterful_attributes"
+  spec.version       = MatterfulAttributes::VERSION
+  spec.authors       = ["Nick Gorbikoff"]
+  spec.email         = ["nick.gorbikoff@gmail.com"]
+  spec.description   = %q{Ruby / Rails gem that shims ActiveRecord::Base to provide some helpful methods for parsing out attributes that matter to humans, i.e. Address.first.matterful_attributes will return a hash of attributes minus id, type, polymorphic_id, polymorphic_type, cretated_at, updated_at and can also skip all foreign_keys, like category_id or status_id. }
+  spec.summary       = %q{See Readme.md}
+  spec.homepage      = "https://github.com/konung/matterful_attributes"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

metadata

@@ -1,18 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: matterful_attributes
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.6
+  prerelease: 
 platform: ruby
 authors:
 - Nick Gorbikoff
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-10 00:00:00.000000000 Z
+date: 2013-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -20,6 +22,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -27,18 +30,20 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: 'Ruby / Rails gem that shims ActiveRecord::Base to provide some helpful
+description: ! 'Ruby / Rails gem that shims ActiveRecord::Base to provide some helpful
   methods for parsing out attributes that matter to humans, i.e. Address.first.matterful_attributes
   will return a hash of attributes minus id, type, polymorphic_id, polymorphic_type,
   cretated_at, updated_at and can also skip all foreign_keys, like category_id or
@@ -60,26 +65,27 @@ files:
 homepage: https://github.com/konung/matterful_attributes
 licenses:
 - MIT
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 1.8.24
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: See Readme.md
 test_files: []
 has_rdoc: 

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 71b08449dae61ecb94fb522f7fa6704a1752ee7c
-  data.tar.gz: 35f693c553e2fda54742fb1dd1d405b02becf49e
-SHA512:
-  metadata.gz: dcae85a5ebe606d6da72088eca64e2f128ce4da5d6b17d80fe2838d83e50ea42746b16bde47eb93c31417b44a219950c6a302480b9c4bce1ea5aecac5329cc74
-  data.tar.gz: 352775d60b8f4629d3d0f7ff3bba2bb04c9437acc35ec6c972bf0dd45de01803a4f5734bf9820435d462c3dbb2844c9fc420593fc58b7e0348c46df5f23e1e93