attr_comparable 0.0.1

data/.gitignore

@@ -0,0 +1 @@
+.idea

data/Gemfile

@@ -0,0 +1,6 @@
+# ruby '1.8.7'
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in attr_default.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,18 @@
+PATH
+  remote: .
+  specs:
+    attr_comparable (0.0.1)
+      minitest
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.0.6)
+    rake (10.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  attr_comparable!
+  rake (>= 0.9)

data/README.md

@@ -0,0 +1,75 @@
+attr_comparable gem
+===================
+
+Mix-in to make a class Comparable, declaratively
+------------------------------------------------
+
+Use `attr_compare <attribute list>`
+to declare the attributes which should be compared, in their order of precedence.
+Attributes may be nil.  nil attributes sort earlier than non-nil to match the SQL behavior for NULL.
+
+Example without AttrComparable
+------------------------------
+
+Consider this value class that holds full names:
+```ruby
+class FullName
+  include Comparable
+  
+  attr_reader :first, :middle, :last, :suffix
+  
+  def initialize(first, middle, last, suffix = nil)
+    @first  = first
+    @middle = middle
+    @last   = last
+    @suffix = suffix
+  end
+  
+  def <=>(other)
+    (last <=> other.last).nonzero? ||
+      (first <=> other.first).nonzero? ||
+        (middle <=> other.middle).nonzero? ||
+          suffix <=> other.suffix
+  end
+end
+```
+You can see that the `<=>` method isn't very DRY, and as shown it doesn't even work with `nil`.
+(That's just too ugly to show.)
+
+Example with AttrComparable
+---------------------------
+Here it is using the gem.  Only the 2 lines with the comments are needed.
+```ruby
+require 'attr_comparable'
+require 'active_support'
+
+class FullName
+  include AttrComparable                        # AttrComparable automatically includes Comparable
+
+  attr_compare :last, :first, :middle, :suffix  # will be compared in this precedence order
+  attr_reader  :first, :middle, :last, :suffix
+
+  def initialize(first, middle, last, suffix = nil)
+    @first  = first
+    @middle = middle
+    @last   = last
+    @suffix = suffix
+  end
+
+  def to_s
+    no_suffix = [first.presence, middle.presence, last.presence].compact.join(' ')
+    [no_suffix, suffix.presence].compact.join(', ')
+  end
+end
+```
+Example Usage
+---------------------------
+```ruby
+>> mom    = FullName.new("Kathy", nil, "Doe")
+>> dad    = FullName.new("John", "Q.", "Public")
+>> junior = FullName.new("John", "Q.", "Public", "Jr.")
+>> junior > dad
+=> true
+>> [mom, dad, junior].sort.map &:to_s
+=> ["Kathy Doe", "John Q. Public", "John Q. Public, Jr."]
+```

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+task :default => :test
+
+desc "Run unit tests."
+task :test do
+  ruby "test/attr_comparable_test.rb"
+end

data/attr_comparable.gemspec

@@ -0,0 +1,18 @@
+require File.expand_path('../lib/attr_comparable/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.add_dependency 'minitest' # Included in Ruby 1.9, but we want the latest.
+  gem.add_development_dependency 'rake', '>=0.9'
+
+  gem.authors       = ["Colin Kelley"]
+  gem.email         = ["colindkelley@gmail.com"]
+  gem.description   = %q{AttrComparable}
+  gem.summary       = %q{Mix-in to make a value class Comparable. Simply declare the order of attributes to compare and the <=> (as needed by Comparable) is generated for you, including support for nil. Includes Comparable.}
+  gem.homepage      = "https://github.com/RingRevenue/attr_comparable"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/.*\.rb})
+  gem.name          = "attr_comparable"
+  gem.version       = AttrComparable::VERSION
+end

data/lib/attr_comparable.rb

@@ -0,0 +1,44 @@
+#
+# Mix-in to make a class Comparable
+#
+# Use attr_comparabie <attribute list>
+# to declare the attributes which should be compared, and the order they should be
+# Attributes may be nil; nil attributes sort earlier than non-nil to match the SQL convention
+#
+module AttrComparable
+  include Comparable
+
+  module ClassMethods
+    # like <=> but handles nil values
+    # when equal, returns nil rather than 0 so the caller can || together
+    def compare_with_nil(left, right)
+      if left.nil?
+        if right.nil?
+          nil
+        else
+          -1
+        end
+      elsif right.nil?
+        1
+      else
+        (left <=> right).nonzero?
+      end
+    end
+
+    def attr_compare(*attributes)
+      attributes = attributes.flatten
+      class_eval <<-EOS
+        def <=>(rhs)
+          #{attributes.map do |attribute|
+              "self.class.compare_with_nil(self.#{attribute}, rhs.#{attribute})"
+            end.join(" || ")
+           } || 0
+        end
+      EOS
+    end
+  end
+
+  def self.included(base_class)
+    base_class.extend ClassMethods
+  end
+end

data/lib/attr_comparable/version.rb

@@ -0,0 +1,3 @@
+module AttrComparable
+  VERSION = '0.0.1'
+end

data/test/attr_comparable_test.rb

@@ -0,0 +1,107 @@
+require File.expand_path('../../lib/attr_comparable',  __FILE__)
+require 'bundler'
+Bundler.require(:default)
+require 'minitest/autorun'
+
+
+class ComparableTestOneParameter
+  include AttrComparable
+  attr_reader :last_name
+  attr_compare :last_name
+
+  def initialize(last_name)
+    @last_name = last_name
+  end
+end
+
+class ComparableTestManyParameters
+  include AttrComparable
+  attr_reader :last_name, :first_name
+  attr_compare :last_name, :first_name
+
+  def initialize(last_name, first_name)
+    @last_name = last_name
+    @first_name = first_name
+  end
+end
+
+
+describe 'AttrComparable' do
+  describe "one parameter" do
+    before do
+      @d1 = ComparableTestOneParameter.new('Jones')
+      @d2 = ComparableTestOneParameter.new('Jones')
+      @d3 = ComparableTestOneParameter.new('Kelley')
+    end
+
+    it "should define <=>" do
+      assert_equal 0,  @d1 <=> @d2
+      assert_equal -1, @d1 <=> @d3
+      assert_equal 1,  @d3 <=> @d1
+    end
+
+    it "should define relative operators like Comparable" do
+      assert @d1.is_a?(Comparable)
+      assert @d1 < @d3
+      assert @d3 >= @d2
+      assert @d1 == @d2
+      assert @d2 != @d3
+    end
+  end
+
+  describe "many parameters" do
+    before do
+      @d1 = ComparableTestManyParameters.new('Jones', 'S')
+      @d2 = ComparableTestManyParameters.new('Jones', 'T')
+      @d3 = ComparableTestManyParameters.new('Jones', 'S')
+      @d4 = ComparableTestManyParameters.new('Kelley', 'C')
+    end
+
+    it "should define <=>" do
+      assert_equal 0,  @d1 <=> @d3
+      assert_equal -1, @d1 <=> @d2
+      assert_equal 1,  @d4 <=> @d1
+    end
+
+    it "should be Comparable" do
+      assert @d1.is_a?(Comparable)
+    end
+
+    it "should define relative operators from Comparable" do
+      assert @d1 < @d2
+      assert @d2 >= @d3
+      assert @d1 == @d3
+      assert @d2 != @d3
+    end
+  end
+
+  it "should be able to compare with nil" do
+    assert_equal nil, ComparableTestManyParameters.compare_with_nil(nil, nil)
+    assert_equal -1, ComparableTestManyParameters.compare_with_nil(nil, 1)
+    assert_equal  1, ComparableTestOneParameter.compare_with_nil(1, nil)
+    assert_equal  1, ComparableTestOneParameter.compare_with_nil("dog", "cat")
+  end
+
+  describe "many parameters with nil" do
+    before do                                                  # sort order
+      @d1 = ComparableTestManyParameters.new(nil, 'S')          # 1
+      @d2 = ComparableTestManyParameters.new('Jones', nil)      # 2
+      @d3 = ComparableTestManyParameters.new(nil, nil)          # 0
+      @d4 = ComparableTestManyParameters.new('Jones', 'S')      # 3
+    end
+
+    it "should define <=> with nil first" do
+      assert_equal 0,  @d1 <=> @d1
+      assert_equal 0,  @d3 <=> @d3
+      assert_equal -1, @d1 <=> @d2
+      assert_equal 1,  @d2 <=> @d3
+      assert_equal -1,  @d2 <=> @d4
+    end
+
+    it "should define relative operators from Comparable" do
+      assert @d1 == @d1
+      assert @d2 > @d3
+      assert @d2 != @d3
+    end
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: attr_comparable
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Colin Kelley
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: AttrComparable
+email:
+- colindkelley@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- attr_comparable.gemspec
+- lib/attr_comparable.rb
+- lib/attr_comparable/version.rb
+- test/attr_comparable_test.rb
+homepage: https://github.com/RingRevenue/attr_comparable
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4162700180279227236
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4162700180279227236
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Mix-in to make a value class Comparable. Simply declare the order of attributes
+  to compare and the <=> (as needed by Comparable) is generated for you, including
+  support for nil. Includes Comparable.
+test_files:
+- test/attr_comparable_test.rb