comparability 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d7df560ce69d77e22e8c096500a37c2ed83c271c
+  data.tar.gz: 959f6c8776ac7c4922246edd4e5d20e68149c4c8
+SHA512:
+  metadata.gz: 66d97494c122f12583f01d78c949a063b28a00d922e4a8a5113edc354e84fe0efbfc248eaf55e956dca16f4319e7c3a1fc6e09b9e54130cbfbc1d8e589ea2bd7
+  data.tar.gz: b3805cdb0f7d3c6a949187b581508fdbbd5965466d63c138ef7d18f8b69660fe0cf17353c1ce21ef378c53efd9ebcdda5ba38e69db7f4edd411951b74a409986

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Ippei Ukai
+
+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

@@ -0,0 +1,126 @@
+# Comparability
+
+Provides Comparator and declarative definition of comparison operator.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'comparability'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install comparability
+
+## Usage
+
+### ComparableBy (Declarative definition of comparison operator)
+
+You can declaratively define your class's comparison with ``comparable_by`` method. 
+To use, you need to extend your class with ``ComparableBy`` module. 
+
+    require 'comparability'
+    
+    class MyClass < Struct.new(:a, :b, :c, :d)
+      extend ComparableBy
+      
+      attr_reader :a, :b, :c, :d, :e
+            
+      comparable_by :a,                              # order of a
+                    [:b, reverse: true],             # reverse order of b
+                    [:c, nil: :first],               # order of c, ordered first if c is nil  
+                    [:d, reverse: true, nil: :last]  # reverse order of d, ordered last if d is nil  
+                    ->(_){ _.e.upcase },             # order of e, case-insensitive    
+    end  
+      
+Call of ``comparable_by`` defines ``<=>`` instance method, and includes ``Comparable`` module.           
+Each parameter to ``comparable_by`` should be either an instance of ``Comparator`` or arguments to ``Comparator.create``
+in order of precedence.             
+           
+### Comparator
+
+Some pre-defined comparisons are accessible with special methods.
+Other variations are created with ``Comparator.create``.
+
+#### natural order
+
+The most simple ``Comparator`` which just evokes the comparison (spaceship) operator.
+ 
+    Comparator.natural_order                 # essentially compare(a,b) is defined as a <=> b
+    Comparator.natural_order(reverse: true)  # b <=> a instead
+    
+#### nil priority
+    
+This special ``Comparator`` orders only by whether object is nil or not.
+     
+    Comparator.prioritize_nil(:first)  # nil is smaller
+    Comparator.prioritize_nil(:last)   # nil is bigger 
+
+#### by attribute value
+
+If you specify a symbol to ``Comparator.create``,
+the comparator will compare objects by the results of the specified method. 
+  
+    Comparator.create(:size)                 # compares by size (prioritise smaller)
+    Comparator.create(:size, reverse: true)  # compares by size (prioritise bigger) 
+    
+You can use ``:nil`` option to specify the priority of nil value.     
+    
+    Comparator.create(:priority, nil: :last)                 # compares by priority (prioritise smaller, last if nil)
+    Comparator.create(:priority, reverse: true, nil: :last)  # compares by priority (prioritise bigger, last if nil) 
+    
+The attribute method can be public or protected, but not private.    
+    
+#### by value extractor        
+
+If you specify a proc with arity 1 to ``Comparator.create``,
+the comparator will compare objects by the results of the specified proc yielding each object. 
+
+You can also pass the comparison as block.
+                                                                                        
+    Comparator.create { |str| str.length }   # compares by length (prioritise shorter)  
+    Comparator.create { |str| -str.length }  # compares by length (prioritise longer)
+            
+#### with proc
+                                                                
+If you specify a proc with arity 2 to ``Comparator.create``,
+it creates a comparator defined by the specified proc.
+ 
+You can also pass the comparison as block.
+ 
+    Comparator.create do |obj1, obj2| 
+      # ... your comparison here ... 
+    end
+               
+#### chaining
+
+You can chain comparators with ``Comparator.chain`` or its alias ``Comparator.[]``.
+
+    Comparator[comparator1, comparator2]  # compares with comparator1, then tie-breaks with comparator2
+
+#### reversing
+
+You can reverse existing comparators with ``Comparator.reverse``.
+
+    Comparator.reverse(comparator)  # reverses the order
+
+#### ``Enumerable#sort`` usage
+
+``Comparator#to_proc`` returns a ``Proc`` compatible with ``Enumerable#sort``.
+You can use the ampersand shorthand to convert a comparator and pass as block. 
+
+    comparator = Comparator[Comparator.prioritize_nil(:last), 
+                            Comparator.natural_order(reverse: true)] 
+    [nil,1,2,3,4].sort(&comparator)  # => [4, 3, 2, 1, nil] 
+
+## Contributing
+
+1. Fork it ( http://github.com/ippeiukai/comparability/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

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

data/comparability.gemspec

@@ -0,0 +1,22 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'comparability/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'comparability'
+  spec.version       = Comparability::VERSION
+  spec.authors       = ['Ippei Ukai']
+  spec.email         = ['ippei@users.sourceforge.net']
+  spec.summary       = 'Provides Comparator and declarative definition of comparison operator.'
+  spec.homepage      = 'http://github.com/ippeiukai/comparability'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x00")
+  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.5'
+  spec.add_development_dependency 'rake'
+end

data/lib/comparability.rb

@@ -0,0 +1,7 @@
+require_relative 'comparability/version'
+
+require_relative 'comparability/comparator'
+Comparator = Comparability::Comparator
+
+require_relative 'comparability/comparable_by'
+ComparableBy = Comparability::ComparableBy

data/lib/comparability/comparable_by.rb

@@ -0,0 +1,20 @@
+# coding: utf-8
+
+module Comparability
+  module ComparableBy
+
+    private
+
+    # @!visibility public
+    # Declares the comparison for this class.
+    # This defines <=> instance method and includes Comparable module.
+    def comparable_by(*args)
+      raise ArgumentError if args.empty?
+      comparator = Comparator.chain(*args)
+      const_set(:COMPARATOR, comparator)
+      define_method(:<=>) { |other| self.class::COMPARATOR.compare(self, other) }
+      include Comparable
+    end
+
+  end
+end

data/lib/comparability/comparator.rb

@@ -0,0 +1,26 @@
+# coding: utf-8
+
+module Comparability
+  class Comparator
+    # @!parse extend Comparability::Comparators::FactoryMethods
+
+    def compare(me, other)
+      me <=> other
+    end
+
+    def to_proc
+      @_to_proc ||= method(:compare).to_proc
+    end
+
+  end
+end
+
+# require files in ./comparators
+File.dirname(File.expand_path(__FILE__)).tap do |this_dirname|
+  Dir[File.join(this_dirname, 'comparators', '**', '*.rb')].each do |file|
+    name = file.gsub(%r|^#{Regexp.escape(this_dirname)}/(.*)#{Regexp.escape('.rb')}|, '\1')
+    require_relative name
+  end
+end
+
+Comparability::Comparator.extend(Comparability::Comparators::FactoryMethods)

data/lib/comparability/comparators/attribute_value_comparator.rb

@@ -0,0 +1,38 @@
+# coding: utf-8
+
+require_relative 'value_comparator'
+
+module Comparability
+  module Comparators
+    class AttributeValueComparator < ValueComparator
+
+      def initialize(attribute)
+        attribute = attribute.to_s.freeze unless attribute.is_a?(Symbol)
+        @attribute = attribute
+      end
+
+      attr_reader :attribute
+
+      private
+
+      def extract_value(me)
+        me.send(attribute)
+      end
+
+      def extract_other_value(me, _other_)
+        if instance_evaluable_attribute?
+          # me can access the protected attribute of the other
+          me.instance_eval("_other_.#{attribute}()")
+        else
+          _other_.public_send(attribute)
+        end
+      end
+
+      INSTANCE_EVALUABLE_METHOD_NAME = /\A([_a-zA-Z][_a-zA-Z0-9]*[!?]?)|([!~+-]@)\Z/
+      def instance_evaluable_attribute?
+        INSTANCE_EVALUABLE_METHOD_NAME =~ attribute
+      end
+
+    end
+  end
+end

data/lib/comparability/comparators/comparator_chain.rb

@@ -0,0 +1,38 @@
+# coding: utf-8
+
+require 'forwardable'
+
+module Comparability
+  module Comparators
+    class ComparatorChain < Comparator
+      extend Forwardable
+      include Enumerable
+
+      def initialize(comparators)
+        raise ArgumentError unless comparators.size > 0
+        raise ArgumentError unless comparators.all? { |c| c.is_a?(Comparator) }
+        @comparators = comparators.freeze
+      end
+
+      attr_reader :comparators
+      delegate :each => :comparators
+
+      def compare(me, other)
+        inject(0) do |zero, comparator|
+          result = comparator.compare(me, other)
+          if result.nil?
+            # the comparator failed
+            return nil
+          elsif result.nonzero?
+            # we have the conclusion
+            return result
+          else
+            # a tie
+            next 0
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/comparability/comparators/factory_methods.rb

@@ -0,0 +1,103 @@
+# coding: utf-8
+
+
+module Comparability
+  module Comparators
+    module FactoryMethods
+
+      def create(comparison = nil, options = {}, &block)
+        comparison ||= block
+        comparator =
+          case comparison
+          when Symbol
+            create_from_symbol(comparison)
+          when Proc
+            create_from_proc(comparison)
+          when ->(_) { _.respond_to?(:to_proc) }
+            create_from_proc(comparison.to_proc)
+          else
+            raise ArgumentError, 'invalid comparison'
+          end
+        apply_options(comparator, options)
+      end
+
+      # @param comparisons [Array]
+      #   each comparison should be either Comparison instance or argument(s) accepted by #create
+      def chain(*comparisons)
+        comparators = comparisons.map do |comparison_or_comparator|
+          case comparison_or_comparator
+          when Comparator
+            comparison_or_comparator
+          else
+            create(*comparison_or_comparator)
+          end
+        end
+        ComparatorChain.new(comparators)
+      end
+      alias_method :[], :chain
+
+      # @param priority [Symbol] :first or :last
+      def prioritize_nil(priority)
+        NilComparator.with_nil_priority(priority)
+      end
+
+      # @option options [true] :reverse
+      def natural_order(options = {})
+        @_natural_order ||= Comparator.new
+        if options[:reverse]
+          @_reverse_natural_order ||= reverse(@_natural_order)
+        else
+          @_natural_order
+        end
+      end
+
+      # @param comparator [Comparator]
+      def reverse(comparator)
+        ReverseWrapperComparator.wrap(comparator)
+      end
+
+      private
+
+      def create_from_symbol(attr)
+        AttributeValueComparator.new(attr)
+      end
+
+      def create_from_proc(proc)
+        case proc.arity
+        when 1
+          ValueExtractorComparator.new(proc)
+        when 2
+          ProcComparator.new(proc)
+        else
+          raise ArgumentError, 'invalid comparison'
+        end
+      end
+
+      def apply_options(comparator, options)
+        nil_value_priority = options.fetch(:nil, nil)
+        reversing = options.fetch(:reverse, false)
+
+        if nil_value_priority
+          raise ArgumentError unless comparator.respond_to?(:nil_value_priority=)
+          if reversing
+            # value comparison should be reversed, but not the nil priority
+            case nil_value_priority
+            when :first
+              nil_value_priority = :last
+            when :last
+              nil_value_priority = :first
+            end
+          end
+          comparator.nil_value_priority = nil_value_priority
+        end
+
+        if reversing
+          comparator = reverse(comparator)
+        end
+
+        comparator
+      end
+
+    end
+  end
+end

data/lib/comparability/comparators/nil_comparator.rb

@@ -0,0 +1,45 @@
+# coding: utf-8
+
+require 'singleton'
+
+module Comparability
+  module Comparators
+    module NilComparator
+
+      class << self
+
+        def with_nil_priority(priority)
+          raise ArgumentError unless %[first last].include?(priority.to_s)
+          public_send("nil_#{priority}")
+        end
+
+        def nil_first
+          @_nil_first ||= ReverseWrapperComparator.wrap(NilLastComparator.instance)
+        end
+
+        def nil_last
+          NilLastComparator.instance
+        end
+
+      end
+
+      class NilLastComparator < Comparator
+        include Singleton
+
+        def compare(me, other)
+          if me.nil? && other.nil?
+            0
+          elsif me.nil?
+            1
+          elsif other.nil?
+            -1
+          else
+            0
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/comparability/comparators/proc_comparator.rb

@@ -0,0 +1,14 @@
+# coding: utf-8
+
+module Comparability
+  module Comparators
+    class ProcComparator < Comparator
+
+      def initialize(comparison)
+        raise ArgumentError unless comparison.is_a?(Proc) && comparison.arity == 2
+        self.singleton_class.send(:define_method, :compare, &comparison)
+      end
+
+    end
+  end
+end

data/lib/comparability/comparators/reverse_wrapper_comparator.rb

@@ -0,0 +1,25 @@
+# coding: utf-8
+
+require_relative 'wrapper_comparator'
+
+module Comparability
+  module Comparators
+    class ReverseWrapperComparator < WrapperComparator
+
+      def compare(me, other)
+        reverse(wrapped_compare(me, other))
+      end
+
+      private
+
+      def reverse(comparison_result)
+        if comparison_result.nil? || comparison_result.zero?
+          comparison_result
+        else
+          -comparison_result
+        end
+      end
+
+    end
+  end
+end

data/lib/comparability/comparators/value_comparator.rb

@@ -0,0 +1,40 @@
+# coding: utf-8
+
+require_relative 'nil_comparator'
+
+module Comparability
+  module Comparators
+    class ValueComparator < Comparator
+
+      def compare(me, other)
+        me_value = extract_value(me)
+        other_value = extract_other_value(me, other)
+
+        if nil_value_priority
+          nil_result = NilComparator.with_nil_priority(nil_value_priority).compare(me_value, other_value)
+          return nil_result if nil_result && nil_result.nonzero?
+        end
+
+        me_value <=> other_value
+      end
+
+      def nil_value_priority=(priority)
+        raise ArgumentError unless [nil, :first, :last].include?(priority)
+        @nil_value_priority = priority
+      end
+
+      attr_reader :nil_value_priority
+
+      private
+
+      def extract_value(me)
+        raise 'abstract'
+      end
+
+      def extract_other_value(me, obj)
+        extract_value(obj)
+      end
+
+    end
+  end
+end

data/lib/comparability/comparators/value_extractor_comparator.rb

@@ -0,0 +1,24 @@
+# coding: utf-8
+
+require_relative 'value_comparator'
+
+module Comparability
+  module Comparators
+    class ValueExtractorComparator < ValueComparator
+
+      def initialize(value_extractor)
+        raise ArgumentError unless value_extractor.is_a?(Proc) && value_extractor.arity == 1
+        @value_extractor = value_extractor
+      end
+
+      private
+
+      attr_reader :value_extractor
+
+      def extract_value(obj)
+        value_extractor.(obj)
+      end
+
+    end
+  end
+end

data/lib/comparability/comparators/wrapper_comparator.rb

@@ -0,0 +1,26 @@
+# coding: utf-8
+
+module Comparability
+  module Comparators
+    class WrapperComparator < Comparator
+
+      class << self
+        alias_method :wrap, :new
+      end
+
+      def initialize(comparator)
+        raise ArgumentError unless comparator.is_a?(Comparator)
+        @wrapped = comparator
+      end
+
+      private
+
+      attr_reader :wrapped
+
+      def wrapped_compare(me, other)
+        wrapped.compare(me, other)
+      end
+
+    end
+  end
+end

data/lib/comparability/version.rb

@@ -0,0 +1,3 @@
+module Comparability
+  VERSION = "1.0.0"
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: comparability
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ippei Ukai
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- ippei@users.sourceforge.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- comparability.gemspec
+- lib/comparability.rb
+- lib/comparability/comparable_by.rb
+- lib/comparability/comparator.rb
+- lib/comparability/comparators/attribute_value_comparator.rb
+- lib/comparability/comparators/comparator_chain.rb
+- lib/comparability/comparators/factory_methods.rb
+- lib/comparability/comparators/nil_comparator.rb
+- lib/comparability/comparators/proc_comparator.rb
+- lib/comparability/comparators/reverse_wrapper_comparator.rb
+- lib/comparability/comparators/value_comparator.rb
+- lib/comparability/comparators/value_extractor_comparator.rb
+- lib/comparability/comparators/wrapper_comparator.rb
+- lib/comparability/version.rb
+homepage: http://github.com/ippeiukai/comparability
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Provides Comparator and declarative definition of comparison operator.
+test_files: []