stable_match 0.1.1 → 0.2.0

data/lib/stable_match/runner.rb

@@ -1,39 +1,37 @@
+require 'yaml'
+require 'stable_match/util/initialize_with_defaults'
+
 module StableMatch
   class Runner
-  ## Whether the sets have been built into candidate sets
-  #
-    fattr( :built ){ false }
+    include Util::InitializeWithDefaults
+
+    # Whether the sets have been built into candidate sets
+    attr_accessor :built
     alias_method :built? , :built
 
-  ## Container for all the candidates
-  #
-    fattr( :candidates ){ [] }
+    # Container for all the candidates
+    attr_accessor :candidates
 
-  ## Whether the sets have been checked for consistency
-  #
-    fattr( :checked ){ false }
+    # Whether the sets have been checked for consistency
+    attr_accessor :checked
     alias_method :checked? , :checked
 
-  ## The first set to use in the matching
-  #
-    fattr( :candidate_set1 ){ {} } # for Candidates
-    fattr :set1                    # raw data
-
-  ## The second set to use in the matching
-  #
-    fattr( :candidate_set2 ){ {} } # for Candidates
-    fattr :set2                    # raw data
-
-  ## The way in which the run loop executes
-  #
-  # Should be either: symmetric OR asymmetric
-  #
-    fattr( :strategy ){ :symmetric }
-
-  ## Runner::run
-  #
-  # Class-level factory method to construct, check, build and run a Runner instance
-  #
+    # The first set to use in the matching
+    attr_accessor \
+      :candidate_set1, # for Candidates
+      :set1            # raw data
+
+    # The second set to use in the matching
+    attr_accessor \
+      :candidate_set2, # for Candidates
+      :set2            # raw data
+
+    # The way in which the run loop executes
+    #
+    # Should be either: symmetric OR asymmetric
+    attr_accessor :strategy
+
+    # Class-level factory method to construct, check, build and run a Runner instance
     def self.run( *args )
       runner = new *args
       runner.check!
@@ -41,52 +39,61 @@ module StableMatch
       runner.run
     end
 
-    def initialize( *args )
-      options = Map.opts args
-      @set1   = options.set1 rescue args.shift or raise ArgumentError.new( "No `set1` provided!" )
-      @set2   = options.set2 rescue args.shift or raise ArgumentError.new( "No `set2` provided!" )
+    def initialize( set1 , set2 , strategy = :symmetric )
+      @set1     = set1
+      @set2     = set2
+      @strategy = strategy
+    end
 
-      @strategy = options.strategy if options.get( :strategy )
+    def initialize_defaults!
+      @built          ||= false
+      @candidates     ||= []
+      @checked        ||= false
+      @candidate_set1 ||= {}
+      @candidate_set2 ||= {}
     end
 
-  ## Runner#build!
-  #
-  # Convert `set1` and `set2` into `candidate_set1` and `candidate_set2`
-  # Also, track a master array of `candidates`
-  # Mark itself as `built`
-  #
+    # Convert `set1` and `set2` into `candidate_set1` and `candidate_set2`
+    # Also, track a master array of `candidates`
+    # Mark itself as `built`
     def build!
       set1.each do | target , options |
-        candidate = Candidate.new target , *[ options ]
+        candidate =
+          Candidate.new \
+            target,
+            *( options.first.is_a?( Array ) ? options : [ options ] )
+
         candidates.push candidate
         candidate_set1[ target ] = candidate
       end
 
       set2.each do | target , options |
-        candidate = Candidate.new target , *[ options ]
+        candidate =
+          Candidate.new \
+            target,
+            *( options.first.is_a?( Array ) ? options : [ options ] )
+
         candidates.push candidate
         candidate_set2[ target ] = candidate
       end
 
       candidate_set1.each do | target , candidate |
-        candidate.preferences.map! { | preference_target | candidate_set2[ preference_target ] }
+        candidate.preferences =
+          candidate.raw_preferences.map { | preference_target | candidate_set2[ preference_target ] }
       end
 
       candidate_set2.each do | target , candidate |
-        candidate.preferences.map! { | preference_target | candidate_set1[ preference_target ] }
+        candidate.preferences =
+          candidate.raw_preferences.map { | preference_target | candidate_set1[ preference_target ] }
       end
 
-    ## We've built the candidates
-    #
+      # We've built the candidates
       self.built = true
     end
 
-  ## Runner#check!
-  #
-  # Run basic checks against each raw set
-  # Meant to be run before being built into candidate sets
-  # Mark itself as `checked`
-  #
+    # Run basic checks against each raw set
+    # Meant to be run before being built into candidate sets
+    # Mark itself as `checked`
     def check!
       error     = proc { | message | raise ArgumentError.new( message ) }
       set1_keys = set1.keys
@@ -94,62 +101,41 @@ module StableMatch
       set1_size = set1.size
       set2_size = set2.size
 
-    ## Check set1
-    #
+      # Check set1
       set1.each do | target , options |
         message = "Preferences for #{ target.inspect } in `set1` do not match availabilities in `set2`!"
+        options = options.first if options.first.is_a?( Array )
         error[ message ] unless \
-        ## Anything there is a preference for is in the other set
-        #
-          ( options[ :preferences ].inject( true ){ | memo , preference | memo && set2_keys.include?( preference ) } )
+          # Anything there is a preference for is in the other set
+          ( options.all? { | preference | set2_keys.include?( preference ) } )
       end
 
-    ## Check set2 the same way
-    #
+      # Check set2 the same way
       set2.each do | target , options |
         message = "Preferences for #{ target.inspect } in `set2` do not match availabilities in `set1`!"
+        options = options.first if options.first.is_a?( Array )
         error[ message ] unless \
-          ( options[ :preferences ].inject( true ){ | memo , preference | memo && set1_keys.include?( preference ) } )
+          # Anything there is a preference for is in the other set
+          ( options.all? { | preference | set1_keys.include?( preference ) } )
       end
 
-    ## We've run the check
-    #
+      # We've run the check
       self.checked = true
     end
 
     def inspect
-      require "yaml"
-
-      inspection = proc do | set |
-        set.keys.inject( Hash.new ) do | hash , key |
-          candidate = set[ key ]
-          preferences = candidate.preferences
-
-          hash.update(
-            key => {
-              'matches'     => candidate.matches.map( &:target ),
-              'preferences' => candidate.preferences.map( &:target ),
-              'proposals'   => candidate.proposals.map( &:target )
-            }
-          )
-        end
-      end
-
-      {
-        'strategy'       => strategy.to_s,
-        'candidate_set1' => inspection[ candidate_set1 ],
-        'candidate_set2' => inspection[ candidate_set2 ]
-      }.to_yaml
+      candidates.map( &:inspect ).join "\n\n"
     end
 
-  ## Runner#remaining_candidates
-  #
-  # This method respects the runner's strategy!
-  #
-  # List the remaining candidates that:
-  # -> have remaining slots available for matches AND
-  # -> have not already proposed to all of their preferences
-  #
+    alias_method \
+      :pretty_inspect,
+      :inspect
+
+    # This method respects the runner's strategy!
+    #
+    # List the remaining candidates that:
+    # -> have remaining slots available for matches AND
+    # -> have not already proposed to all of their preferences
     def remaining_candidates
       case strategy.to_sym
       when :symmetric
@@ -159,12 +145,9 @@ module StableMatch
       end
     end
 
-  ## Runner#run
-  #
-  # While there are remaining candidates, ask each one to propose to all of their preferences until:
-  # -> a candidate has proposed to all of their preferences
-  # -> a candidate has no more `matching_positions` to be filled
-  #
+    # While there are remaining candidates, ask each one to propose to all of their preferences until:
+    # -> a candidate has proposed to all of their preferences
+    # -> a candidate has no more `matching_positions` to be filled
     def run
       while ( rcs = remaining_candidates ).any?
         rcs.each do | candidate |

data/lib/stable_match/test.rb

@@ -0,0 +1,49 @@
+require 'stable_match'
+require 'minitest/test'
+
+module StableMatch
+  class Test < Minitest::Test
+    alias_method '__assert__' , 'assert'
+
+    # See: https://github.com/ahoward/testing.rb/blob/08dd643239a23543409ecb5fee100181f1621794/lib/testing.rb#L82-107
+    #
+    # Override assert to take a few different kinds of options
+    # Most notable argument type is a block that:
+    # -> asserts no exceptions were raised
+    # -> asserts the result of the block is truthy
+    # -> returns the result of the block
+    def assert( *args , &block )
+      if args.size == 1 and args.first.is_a?(Hash)
+        options  = args.first
+        expected = getopt(:expected, options){ missing }
+        actual   = getopt(:actual, options){ missing }
+        if expected == missing and actual == missing
+          actual , expected , *_ = options.to_a.flatten
+        end
+        expected = expected.call() if expected.respond_to?(:call)
+        actual   = actual.call() if actual.respond_to?(:call)
+        assert_equal expected , actual
+      end
+
+      if block
+        label   = "assert(#{ args.join(' ') })"
+        result  = nil
+        raised  = false
+        result  = begin
+                    block.call
+                  rescue Object => e
+                    raised = e
+                    false
+                  end
+        __assert__ !raised , ( raised.message rescue label )
+        __assert__ result  , label
+        result
+      else
+        result = args.shift
+        label  = "assert(#{ args.join(' ') })"
+        __assert__ result , label
+        result
+      end
+    end
+  end
+end

data/lib/stable_match/util.rb

@@ -0,0 +1 @@
+require 'stable_match/util/initialize_with_defaults'

data/lib/stable_match/util/initialize_with_defaults.rb

@@ -0,0 +1,27 @@
+module StableMatch
+  module Util
+    module InitializeWithDefaults
+      def self.included( klass )
+        klass.extend ClassMethods
+      end
+
+      module ClassMethods
+        def new( *args , &block )
+          object = allocate
+
+          object.initialize_defaults!
+
+          object.send \
+            :initialize,
+            *args,
+            &block
+
+          object
+        end
+      end
+
+      def initialize_defaults!
+      end
+    end
+  end
+end

data/lib/stable_match/version.rb

@@ -1,3 +1,3 @@
 module StableMatch
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/stable_match.gemspec

@@ -2,27 +2,19 @@
 require File.expand_path('../lib/stable_match/version', __FILE__)
 
 Gem::Specification.new do | gem |
-  gem.authors       = [ "Ryan Cook" , "Ara Howard" ]
-  gem.email         = [ "cookrn@gmail.com" , "ara.t.howard@gmail.com" ]
+  gem.authors       = [ 'Ryan Cook' , 'Ara Howard' ]
+  gem.email         = [ 'cookrn@gmail.com' , 'ara.t.howard@gmail.com' ]
   gem.description   = %q{A generic implementation of the stable match algorightm.}
   gem.summary       = %q{stable_match v0.1.0}
-  gem.homepage      = "https://github.com/cookrn/stable_match"
+  gem.homepage      = 'https://github.com/cookrn/stable_match'
 
   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)/})
-  gem.name          = "stable_match"
-  gem.require_paths = [ "lib" ]
+  gem.name          = 'stable_match'
+  gem.require_paths = [ 'lib' ]
   gem.version       = StableMatch::VERSION
 
-## Runtime Dependencies
-#
-  gem.add_dependency "fattr" , "~> 2.2.1"
-  gem.add_dependency "map"   , "~> 5.5.0"
-
-## Development Dependencies
-#
-  gem.add_development_dependency "minitest" , "~> 2.12.1"
-  gem.add_development_dependency "rake"     , "~> 0.9.2.2"
-  gem.add_development_dependency "rego"     , "~> 1.0.0"
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'rake'
 end

data/test/functional/nrmp_test.rb

@@ -1,23 +1,23 @@
-require "test_helper"
+require 'test_helper'
 
-class NationalResidentMatchingProgramFunctionalTest < MiniTest::Unit::TestCase
+class NrmpTest < StableMatch::Test
   def test_case
     programs = {
-      'mercy'   => { :match_positions => 2, :preferences => ['chen', 'garcia']},
-      'city'    => { :match_positions => 2, :preferences => ['garcia', 'hassan', 'eastman', 'anderson', 'brown', 'chen', 'davis', 'ford']},
-      'general' => { :match_positions => 2, :preferences => ['brown', 'eastman', 'hassan', 'anderson', 'chen', 'davis', 'garcia']},
-      'state'   => { :match_positions => 2, :preferences => ['brown', 'eastman', 'anderson', 'chen', 'hassan', 'ford', 'davis', 'garcia']}
+      'mercy'   => [ ['chen', 'garcia'] , 2 ],
+      'city'    => [ ['garcia', 'hassan', 'eastman', 'anderson', 'brown', 'chen', 'davis', 'ford'] , 2 ],
+      'general' => [ ['brown', 'eastman', 'hassan', 'anderson', 'chen', 'davis', 'garcia'] , 2 ],
+      'state'   => [ ['brown', 'eastman', 'anderson', 'chen', 'hassan', 'ford', 'davis', 'garcia'] , 2 ]
     }
 
     applicants = {
-      'anderson' => { :match_positions => 1 , :preferences => ['city'] },
-      'brown'    => { :match_positions => 1 , :preferences => ['city', 'mercy'] },
-      'chen'     => { :match_positions => 1 , :preferences => ['city', 'mercy'] },
-      'davis'    => { :match_positions => 1 , :preferences => ['mercy', 'city', 'general', 'state'] },
-      'eastman'  => { :match_positions => 1 , :preferences => ['city', 'mercy', 'state', 'general'] },
-      'ford'     => { :match_positions => 1 , :preferences => ['city', 'general', 'mercy', 'state'] },
-      'garcia'   => { :match_positions => 1 , :preferences => ['city', 'mercy', 'state', 'general'] },
-      'hassan'   => { :match_positions => 1 , :preferences => ['state', 'city', 'mercy', 'general' ] }
+      'anderson' => [ 'city' ],
+      'brown'    => [ 'city'  , 'mercy' ],
+      'chen'     => [ 'city'  , 'mercy' ],
+      'davis'    => [ 'mercy' , 'city'    , 'general' , 'state'   ],
+      'eastman'  => [ 'city'  , 'mercy'   , 'state'   , 'general' ],
+      'ford'     => [ 'city'  , 'general' , 'mercy'   , 'state'   ],
+      'garcia'   => [ 'city'  , 'mercy'   , 'state'   , 'general' ],
+      'hassan'   => [ 'state' , 'city'    , 'mercy'   , 'general' ]
     }
 
     programs_expectations = {
@@ -38,14 +38,15 @@ class NationalResidentMatchingProgramFunctionalTest < MiniTest::Unit::TestCase
       'hassan'   => [ 'state' ]
     }
 
-    runner = StableMatch.run applicants , programs , :strategy => :asymmetric
+    runner = StableMatch.run applicants , programs , :asymmetric
 
     ## applicants
     #
       applicants_expectations.each do | applicant , expected_matches |
         candidate      = runner.candidate_set1[ applicant ]
         actual_matches = candidate.matches.map &:target
-        assert{ expected_matches.sort == actual_matches.sort }
+        assertion = "#{ applicant } matches #{ actual_matches }"
+        assert( assertion ){ expected_matches.sort == actual_matches.sort }
       end
 
     ## programs
@@ -53,6 +54,7 @@ class NationalResidentMatchingProgramFunctionalTest < MiniTest::Unit::TestCase
       programs_expectations.each do | program , expected_matches |
         candidate      = runner.candidate_set2[ program ]
         actual_matches = candidate.matches.map &:target
+        assertion = "#{ program } matches #{ actual_matches }"
         assert{ expected_matches.sort == actual_matches.sort }
       end
   end

data/test/functional/stable_marriage_test.rb

@@ -0,0 +1,75 @@
+require 'test_helper'
+
+class StableMarriageTest < StableMatch::Test
+  def test_case
+    men = {
+      'abe'  => %w(abi eve cath ivy jan dee fay bea hope gay),
+      'bob'  => %w(cath hope abi dee eve fay bea jan ivy gay),
+      'col'  => %w(hope eve abi dee bea fay ivy gay cath jan),
+      'dan'  => %w(ivy fay dee gay hope eve jan bea cath abi),
+      'ed'   => %w(jan dee bea cath fay eve abi ivy hope gay),
+      'fred' => %w(bea abi dee gay eve ivy cath jan hope fay),
+      'gav'  => %w(gay eve ivy bea cath abi dee hope jan fay),
+      'hal'  => %w(abi eve hope fay ivy cath jan bea gay dee),
+      'ian'  => %w(hope cath dee gay bea abi fay ivy jan eve),
+      'jon'  => %w(abi fay jan gay eve bea dee cath ivy hope)
+    }
+
+    women = {
+      'abi'  => %w(bob fred jon gav ian abe dan ed col hal),
+      'bea'  => %w(bob abe col fred gav dan ian ed jon hal),
+      'cath' => %w(fred bob ed gav hal col ian abe dan jon),
+      'dee'  => %w(fred jon col abe ian hal gav dan bob ed),
+      'eve'  => %w(jon hal fred dan abe gav col ed ian bob),
+      'fay'  => %w(bob abe ed ian jon dan fred gav col hal),
+      'gay'  => %w(jon gav hal fred bob abe col ed dan ian),
+      'hope' => %w(gav jon bob abe ian dan hal ed col fred),
+      'ivy'  => %w(ian col hal gav fred bob abe ed jon dan),
+      'jan'  => %w(ed hal gav abe bob jon col ian fred dan)
+    }
+
+    mens_expectations = {
+      'abe'  => [ 'ivy' ],
+      'bob'  => [ 'cath' ],
+      'col'  => [ 'dee' ],
+      'dan'  => [ 'fay' ],
+      'ed'   => [ 'jan' ],
+      'fred' => [ 'bea' ],
+      'gav'  => [ 'gay' ],
+      'hal'  => [ 'eve' ],
+      'ian'  => [ 'hope' ],
+      'jon'  => [ 'abi' ]
+    }
+
+    womens_expectations = {
+      'abi'  => [ 'jon' ],
+      'bea'  => [ 'fred' ],
+      'cath' => [ 'bob' ],
+      'dee'  => [ 'col' ],
+      'eve'  => [ 'hal' ],
+      'fay'  => [ 'dan' ],
+      'gay'  => [ 'gav' ],
+      'hope' => [ 'ian' ],
+      'ivy'  => [ 'abe' ],
+      'jan'  => [ 'ed' ]
+    }
+
+    runner = StableMatch.run men , women , :asymmetric
+
+    ## men
+    #
+      mens_expectations.each do | man , expected_matches |
+        candidate      = runner.candidate_set1[ man ]
+        actual_matches = candidate.matches.map &:target
+        assert{ expected_matches.sort == actual_matches.sort }
+      end
+
+    ## women
+    #
+      womens_expectations.each do | woman , expected_matches |
+        candidate      = runner.candidate_set2[ woman ]
+        actual_matches = candidate.matches.map &:target
+        assert{ expected_matches.sort == actual_matches.sort }
+      end
+  end
+end