stable_match 0.1.0

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+gemspec
+
+group :development do
+  gem "pry" , "~> 0.9.9.4"
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Ryan Cook
+
+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,29 @@
+# StableMatch
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'stable_match'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install stable_match
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,51 @@
+#!/usr/bin/env rake
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+namespace :examples do
+  desc "Run any example"
+  task :any do
+    exec "ruby #{ Dir[ "#{ File.dirname File.expand_path( __FILE__ ) }/examples/**/*.rb" ].first }"
+  end
+end
+task :example => "examples:any"
+
+namespace :test do
+  desc "Run All The Tests"
+  task :all => [ "test:unit" ]
+
+  desc "Run The Unit Tests"
+  Rake::TestTask.new( :unit ) do | t |
+    t.libs    = [ "test" ]
+    t.pattern = "test/unit/**/*_test.rb"
+    t.verbose = true
+  end
+
+  desc "Start a watcher process that runs the tests on file changes in `lib` or `test` dirs"
+  task :watch do
+    exec "rego {lib,test} -- rake"
+  end
+end
+
+desc "Run All The Tests"
+task :test    => "test:all"
+task :default => :test
+
+BEGIN {
+  def load_bundle_env!
+    is_blank = lambda { |o| o.nil? or o.size < 1 }
+    ENV[ "BUNDLE_GEMFILE" ] = File.expand_path( "Gemfile" ) unless !is_blank[ ENV[ "BUNDLE_GEMFILE" ] ]
+    begin
+      require "bundler"
+    rescue
+      require "rubygems"
+      require "bundler"
+    ensure
+      raise LoadError.new( "Bundler not found!" ) unless defined?( Bundler )
+      require "bundler/setup"
+    end
+  end
+
+  load_bundle_env! unless defined?( Bundler )
+}

data/examples/example_1.rb

@@ -0,0 +1,27 @@
+require "stable_match"
+
+class Test
+  PROGRAMS = {
+    'city'    => { :match_positions => 1, :preferences => ['garcia', 'hassan', 'eastman', 'brown', 'chen', 'davis', 'ford']},
+    'general' => { :match_positions => 3, :preferences => ['brown', 'eastman', 'hassan', 'anderson', 'chen', 'davis', 'garcia']},
+    'mercy'   => { :match_positions => 1, :preferences => ['chen', 'garcia', 'brown']},
+    'state'   => { :match_positions => 1, :preferences => ['anderson', 'brown', 'eastman', 'chen', 'hassan', 'ford', 'davis', 'garcia']}
+  }
+
+  APPLICANTS = {
+    'anderson' => { :match_positions => 1 , :preferences => ['state', 'city'] },
+    'brown'    => { :match_positions => 2 , :preferences => ['city', 'mercy', 'state'] },
+    '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' ] }
+  }
+
+  def self.main
+    p StableMatch.run(APPLICANTS, PROGRAMS)
+  end
+end
+
+Test.main

data/lib/stable_match.rb

@@ -0,0 +1,12 @@
+require "fattr"
+require "map"
+
+module StableMatch
+  def self.run( *args , &block )
+    Runner.run *args , &block
+  end
+end
+
+require "stable_match/candidate"
+require "stable_match/runner"
+require "stable_match/version"

data/lib/stable_match/candidate.rb

@@ -0,0 +1,194 @@
+module StableMatch
+  class Candidate
+  ## The matches this candidate has attained
+  #
+    fattr( :matches ){ [] }
+
+  ## The number of matches the candidate is able to make
+  #
+    fattr( :match_positions ){ 1 }
+
+  ## The tracked position for preferences that have been attempted for matches
+  #
+    fattr( :preference_position ){ -1 }
+
+  ## An ordered array of candidates where, the lower the index, the higher the preference
+  #
+  # WARNING -- this may be instantiated with targets at first that get converted to Candidates
+  #
+    fattr( :preferences ){ [] }
+
+  ## The array to track proposals that have already been made
+  #
+    fattr( :proposals ){ [] }
+
+  ## The object that the candidate represents
+  #
+    fattr :target
+
+    def initialize(*args)
+      options      = Map.opts(args)
+      @target      = options.target      rescue args.shift or raise ArgumentError.new( "No `target` provided!" )
+      @preferences = options.preferences rescue args.shift or raise ArgumentError.new( "No `preferences` provided!" )
+
+      @match_positions = options.match_positions if options.get( :match_positions )
+    end
+
+  ## Candidate#better_match?
+  #
+  # Is the passed candidate a better match than any of the current matches?
+  #
+  # ARG: `other` -- another Candidate instance to check against the current set
+  #
+    def better_match?( other )
+      return true if prefers?( other ) && free?
+      preference_index = preferences.index other
+      match_preference_indexes = matches.map { | match | preferences.index match }
+      preference_index and match_preference_indexes.any? { |i| i > preference_index }
+    end
+
+  ## Candidate#exhausted_preferences?
+  #
+  # Have all possible preferences been cycled through?
+  #
+    def exhausted_preferences?
+      preference_position >= preferences.size - 1
+    end
+
+  ## Candidate#free?
+  #
+  # Is there available positions for more matches based on the defined `match_positions`?
+  #
+    def free?
+      matches.length < match_positions
+    end
+
+  ## Candidate#free!
+  #
+  # Delete the least-preferred candidate from the matches array
+  #
+    def free!
+      return false if matches.empty?
+      match_preference_indexes = matches.map { | match | preferences.index match }
+      max                      = match_preference_indexes.max # The index of the match with the lowest preference
+      candidate_to_reject      = preferences[ max ]
+
+    ## Delete from both sides
+    #
+      candidate_to_reject.matches.delete self
+      self.matches.delete candidate_to_reject
+    end
+
+  ## Candidate#full?
+  #
+  # Are there no remaining positions available for matches?
+  #
+    def full?
+      !free?
+    end
+
+    def inspect
+      require "yaml"
+
+      {
+        :target              => target,
+        :match_positions     => match_positions,
+        :matches             => matches.map( &:target ),
+        :preference_position => preference_position,
+        :preferences         => preferences.map( &:target ),
+        :proposals           => proposals.map( &:target )
+      }.to_yaml
+    end
+
+  ## Candidate#match!
+  #
+  # Match with another Candidate
+  #
+  # ARG: `other` -- another Candidate instance to match with
+  #
+    def match!( other )
+      return false unless prefers?( other ) && !matched?( other )
+      matches       << other
+      other.matches << self
+    end
+
+  ## Candidate#matched?
+  #
+  # If no argument is passed: Do we have at least as many matches as available `match_positions`?
+  # If another Candidate is passed: Is that candidate included in the matches?
+  #
+  # ARG: `other` [optional] -- another Candidate instance
+  #
+    def matched?( other = nil )
+      return full? if other.nil?
+      matches.include? other
+    end
+
+  ## Candidate#next_preference!
+  #
+  # Increment `preference_position` and return the preference at that position
+  #
+    def next_preference!
+      self.preference_position += 1
+      preferences.fetch preference_position
+    end
+
+  ## Candidate#prefers?
+  #
+  # Is there a preference for the passed Candidate?
+  #
+  # ARG: `other` -- another Candidate instance
+  #
+    def prefers?( other )
+      preferences.include? other
+    end
+
+  ## Candidate#propose_to
+  #
+  # Track that a proposal was made then ask the other Candidate to respond to a proposal
+  #
+  # ARG: `other` -- another Candidate instance
+  #
+    def propose_to( other )
+      proposals << other
+      other.respond_to_proposal_from self
+    end
+
+  ## Candidate#propose_to_next_preference
+  #
+  # Send a proposal to the next tracked preference
+  #
+    def propose_to_next_preference
+      propose_to next_preference!
+    end
+
+  ## Candidate#respond_to_proposal_from
+  #
+  # Given another candidate, respond properly based on current state
+  #
+  # ARG: `other` -- another Candidate instance
+  #
+    def respond_to_proposal_from( other )
+      case
+      ## Is there a preference for the candidate?
+      #
+        when !prefers?( other )
+          false
+
+      ## Are there available positions for more matches?
+      #
+        when free?
+          match! other
+
+      ## Is the passed Candidate a better match than any other match?
+      #
+        when better_match?( other )
+          free!
+          match! other
+
+        else
+          false
+      end
+    end
+  end
+end

data/lib/stable_match/runner.rb

@@ -0,0 +1,165 @@
+module StableMatch
+  class Runner
+  ## Whether the sets have been built into candidate sets
+  #
+    fattr( :built ){ false }
+    alias_method :built? , :built
+
+  ## Container for all the candidates
+  #
+    fattr( :candidates ){ [] }
+
+  ## Whether the sets have been checked for consistency
+  #
+    fattr( :checked ){ false }
+    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
+
+  ## Runner::run
+  #
+  # Class-level factory method to construct, check, build and run a Runner instance
+  #
+    def self.run( *args , &block )
+      runner = new *args , &block
+      runner.check!
+      runner.build!
+      runner.run
+    end
+
+    def initialize( *args , &block )
+      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!" )
+
+      yield self if block_given?
+    end
+
+  ## Runner#build!
+  #
+  # 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 ]
+        candidates.push candidate
+        candidate_set1[ target ] = candidate
+      end
+
+      set2.each do | target , options |
+        candidate = Candidate.new target , *[ options ]
+        candidates.push candidate
+        candidate_set2[ target ] = candidate
+      end
+
+      candidate_set1.each do | target , candidate |
+        candidate.preferences.map! { | preference_target | candidate_set2[ preference_target ] }
+      end
+
+      candidate_set2.each do | target , candidate |
+        candidate.preferences.map! { | preference_target | candidate_set1[ preference_target ] }
+      end
+
+    ## 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`
+  #
+    def check!
+      error     = proc { | message | raise ArgumentError.new( message ) }
+      set1_keys = set1.keys
+      set2_keys = set2.keys
+      set1_size = set1.size
+      set2_size = set2.size
+
+    ## Check set1
+    #
+      set1.each do | target , options |
+        message = "Preferences for #{ target.inspect } in `set1` do not match availabilities in `set2`!"
+        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 ) } )
+      end
+
+    ## Check set2 the same way
+    #
+      set2.each do | target , options |
+        message = "Preferences for #{ target.inspect } in `set2` do not match availabilities in `set1`!"
+        error[ message ] unless \
+          ( options[ :preferences ].inject( true ){ | memo , preference | memo && set1_keys.include?( preference ) } )
+      end
+
+    ## 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
+
+      {
+        'candidate_set1' => inspection[ candidate_set1 ],
+        'candidate_set2' => inspection[ candidate_set2 ]
+      }.to_yaml
+    end
+
+  ## Runner#remaining_candidates
+  #
+  # List the remaining candidates that:
+  # -> have remaining slots available for matches AND
+  # -> have not already proposed to all of their preferences
+  #
+    def remaining_candidates
+      candidates.reject{ | candidate | candidate.full? || candidate.exhausted_preferences? }
+    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
+  #
+    def run
+      while ( rcs = remaining_candidates ).any?
+        rcs.each do | candidate |
+          while !candidate.exhausted_preferences? && candidate.free?
+            candidate.propose_to_next_preference
+          end
+        end
+      end
+      self
+    end
+  end
+end

data/lib/stable_match/version.rb

@@ -0,0 +1,3 @@
+module StableMatch
+  VERSION = "0.1.0"
+end

data/stable_match.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+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.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.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.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"
+end

data/test/support/minitest.rb

@@ -0,0 +1,51 @@
+module MiniTest
+  class Unit
+    class TestCase
+      alias_method '__assert__' , 'assert'
+
+    ## TestCase#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
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+require "rubygems"
+gem "minitest"
+
+require "minitest/autorun"
+require "minitest/pride"
+
+support_dir = File.expand_path File.dirname( __FILE__ ) , "support"
+Dir[ "#{ support_dir }/**/*.rb" ].each { | f | require f }
+
+require "stable_match"

data/test/unit/stable_match/candidate_test.rb

@@ -0,0 +1,189 @@
+require "test_helper"
+
+class StableMatch::CandidateTest < MiniTest::Unit::TestCase
+  def setup
+    @candidate1 = StableMatch::Candidate.new 1 , [ 2 , 3 ]
+    @candidate2 = StableMatch::Candidate.new 2 , [ 1 , 3 ]
+    @candidate3 = StableMatch::Candidate.new 3 , [ 2 , 1 ]
+
+    @candidate1.preferences = [ @candidate2 , @candidate3 ]
+    @candidate2.preferences = [ @candidate1 , @candidate3 ]
+    @candidate3.preferences = [ @candidate2 , @candidate1 ]
+  end
+
+## Candidate#initialize
+#
+  def test_accepts_args_as_named_options_or_positionally
+    target      = 1
+    preferences = 2
+
+    assert{ StableMatch::Candidate.new( target , preferences ) }
+    assert{ StableMatch::Candidate.new( :target => target , :preferences => preferences ) }
+
+    candidate = assert{ StableMatch::Candidate.new( target , :preferences => preferences ) }
+    assert{ candidate.target == target }
+
+    candidate = assert{ StableMatch::Candidate.new( preferences , :target => target ) }
+    assert{ candidate.preferences == preferences }
+  end
+
+  def test_match_positions_option_overrides_default
+    assert{ @candidate1.match_positions }
+
+    match_positions = 3
+    candidate       = StableMatch::Candidate.new( 1 , [ 2 , 3 ] , :match_positions => match_positions )
+    assert{ candidate.match_positions == match_positions }
+  end
+
+## Candidate#better_match?
+#
+  def test_better_match_returns_false_if_not_preferred
+    candidate4 = StableMatch::Candidate.new 4 , [ @candidate3 , @candidate2 ]
+    assert{ !@candidate1.better_match?( candidate4 ) }
+  end
+
+  def test_better_match_returns_false_if_already_matched
+    @candidate1.match! @candidate2
+    assert{ !@candidate1.better_match?( @candidate2 ) }
+  end
+
+  def test_better_match_returns_true_if_free
+    assert{ @candidate1.better_match? @candidate2 }
+  end
+
+  def test_better_match_returns_true_if_other_has_higher_preference
+    @candidate1.match! @candidate3
+    assert{ @candidate1.better_match? @candidate2 }
+  end
+
+## Candidate#exhausted_preferences?
+#
+  def test_exhausted_preferences_returns_false_if_not_all_preferences_have_been_checked
+    assert{ !@candidate1.exhausted_preferences? }
+  end
+
+  def test_exhausted_preferences_returns_true_if_all_preferences_have_been_checked
+    @candidate1.preference_position = @candidate1.preferences.size
+    assert{ @candidate1.exhausted_preferences? }
+  end
+
+## Candidate#free?
+#
+  def test_free_returns_false_if_all_match_positions_are_filled
+    @candidate1.match! @candidate2
+    assert{ !@candidate1.free? }
+  end
+
+  def test_free_returns_true_if_not_all_match_positions_are_filled
+    assert{ @candidate1.free? }
+  end
+
+## Candidate#free!
+#
+  def test_free_returns_false_if_there_are_no_matches
+    assert{ !@candidate1.free! }
+  end
+
+  def test_free_deletes_the_least_preferred_match
+    @candidate1.match! @candidate2
+    assert{ @candidate1.free! }
+    assert{ !@candidate1.matches.include?( @candidate2 ) }
+  end
+
+  def test_free_deletes_the_least_preferred_match_from_both_sides
+    @candidate1.match! @candidate2
+    assert{ @candidate1.free! }
+    assert{ !@candidate2.matches.include?( @candidate1 ) }
+  end
+
+## Candidate#full?
+#
+  def test_free_returns_false_if_all_match_positions_are_filled
+    @candidate1.match! @candidate2
+    assert{ @candidate1.full? }
+  end
+
+  def test_free_returns_true_if_not_all_match_positions_are_filled
+    assert{ !@candidate1.full? }
+  end
+
+## Candidate#match!
+#
+  def test_match_returns_false_if_other_is_not_preferred
+    candidate4 = StableMatch::Candidate.new 4 , [ @candidate3 , @candidate2 ]
+    assert{ !@candidate1.match!( candidate4 ) }
+  end
+
+  def test_match_returns_false_if_already_matched
+    assert{ @candidate1.match! @candidate2 }
+    assert{ !@candidate1.match!( @candidate2 ) }
+  end
+
+  def test_match_adds_other_to_matches_array
+    assert{ @candidate1.match! @candidate2 }
+    assert{ @candidate1.matches.include? @candidate2 }
+  end
+
+  def test_match_adds_self_to_others_matches_array
+    assert{ @candidate1.match! @candidate2 }
+    assert{ @candidate2.matches.include? @candidate1 }
+  end
+
+## Candidate#matched?
+#
+  def test_matched_returns_full_with_no_args
+    @candidate1.match! @candidate2
+    assert{ @candidate1.matched? == @candidate1.full? }
+  end
+
+  def test_matched_returns_whether_passed_candidate_is_a_match
+    @candidate1.match! @candidate2
+    assert{ @candidate1.matched? @candidate2 }
+  end
+
+## Candidate#next_preference!
+#
+  def test_next_preference_increments_the_preference_position
+    preference_position = @candidate1.preference_position
+    assert{ @candidate1.next_preference! }
+    assert{ preference_position != @candidate1.preference_position }
+  end
+
+  def test_next_preference_returns_a_candidate
+    expected_candidate = @candidate1.preferences.first
+    assert{ expected_candidate == @candidate1.next_preference! }
+  end
+
+## Candidate#prefers?
+#
+  def test_prefers_checks_for_existence_of_candidate_in_preferences
+    assert{ @candidate1.prefers? @candidate2 }
+    assert{ !@candidate1.prefers?( "bogus" ) }
+  end
+
+## Candidate#propose_to
+#
+  def test_propose_to_tracks_proposals
+    assert{ @candidate1.propose_to @candidate2 }
+    assert{ @candidate1.proposals.include? @candidate2 }
+  end
+
+## Candidate#respond_to_proposal_from
+#
+  def test_respond_to_proposal_from_returns_false_if_other_is_not_preferred
+    candidate4 = StableMatch::Candidate.new 4 , [ @candidate3 , @candidate2 ]
+    assert{ !@candidate1.respond_to_proposal_from( candidate4 ) }
+  end
+
+  def test_respond_to_proposal_from_matches_if_preferred_and_free
+    assert{ @candidate1.respond_to_proposal_from @candidate2 }
+  end
+
+  def test_respond_to_proposal_from_frees_and_matches_if_full
+    assert{ @candidate1.respond_to_proposal_from @candidate3 }
+    assert{ @candidate3.matched? @candidate1 }
+    assert{ @candidate1.respond_to_proposal_from @candidate2 }
+    assert{ @candidate2.matched? @candidate1 }
+    assert{ !@candidate3.matched?( @candidate1 ) }
+  end
+end

data/test/unit/stable_match/runner_test.rb

@@ -0,0 +1,121 @@
+require "test_helper"
+
+class StableMatch::RunnerTest < MiniTest::Unit::TestCase
+  def setup
+    @set1 = { 1 => { :preferences => [ 2 ] } }
+    @set2 = { 2 => { :preferences => [ 1 ] } }
+  end
+
+## Runner::run
+#
+  def test_has_a_factory_class_method_that_automatically_runs_match
+    runner = assert{ StableMatch::Runner.run @set1 , @set2 }
+    assert{ runner.checked? }
+    assert{ runner.built? }
+  end
+
+## Runner#initialize
+#
+  def test_accepts_args_as_named_options_or_positionally
+    assert{ StableMatch::Runner.new( @set1 , @set2 ) }
+    assert{ StableMatch::Runner.new( :set1 => @set1 , :set2 => @set2 ) }
+
+    runner = assert{ StableMatch::Runner.new( @set1 , :set2 => @set2 ) }
+    assert{ runner.set1 == @set1 }
+
+    runner = assert{ StableMatch::Runner.new( @set2 , :set1 => @set1 ) }
+    assert{ runner.set2 == @set2 }
+  end
+
+## Runner#build!
+#
+  def test_build_creates_candidate_sets_from_each_raw_set
+    runner = build_runner
+    assert{ runner.build! }
+
+    assert{ !runner.candidate_set1.empty? }
+    assert{ runner.candidate_set1[ @set1.keys.first ] }
+
+    assert{ !runner.candidate_set2.empty? }
+    assert{ runner.candidate_set2[ @set2.keys.first ] }
+  end
+
+  def test_build_adds_to_list_of_candidates
+    runner = build_runner
+    assert{ runner.candidates.empty? }
+    assert{ runner.build! }
+    assert{ !runner.candidates.empty? }
+  end
+
+  def test_build_replaces_candidates_preferences_with_candidates
+    runner = build_runner.tap { | r | r.build! }
+    assert{ runner.candidate_set1.values.first.preferences.all? { | c | c.is_a? StableMatch::Candidate } }
+  end
+
+  def test_build_marks_runner_as_built
+    runner = build_runner
+    assert{ runner.build! }
+    assert{ runner.built }
+    assert{ runner.built? }
+  end
+
+## Runner#check!
+#
+  def test_checks_that_sets_meet_criteria
+    runner = build_runner
+    assert{ runner.check! }
+    assert{ runner.checked }
+    assert{ runner.checked? }
+  end
+
+  def test_checks_that_a_sets_preferences_are_included_in_other_set
+    set1 = { 1 => { :preferences => [ 2 ] } }
+    set2 = { 2 => { :preferences => [ 1 , 3 ] } }
+    runner = StableMatch::Runner.new set1 , set2
+
+    assert "set2 contains a preference for 3 that does not exist" do
+      raised = false
+      begin
+        runner.check!
+      rescue Object => e
+        raised = e.is_a? ArgumentError
+      end
+      raised
+    end
+  end
+
+## Runner#remaining_candidates
+#
+  def test_remaining_candidates_rejects_candidates_that_have_filled_match_positions
+    runner = build_prepared_runner
+    original_size = runner.remaining_candidates.size
+    runner.candidates.first.tap { | c | c.propose_to_next_preference }
+    assert{ original_size > runner.remaining_candidates.size }
+  end
+
+  def test_remaining_candidates_rejects_candidates_that_have_made_all_possible_proposals
+    runner = build_prepared_runner
+    original_size = runner.remaining_candidates.size
+    runner.candidates.first.tap { | c | c.preference_position = c.preferences.size - 1 }
+    assert{ original_size > runner.remaining_candidates.size }
+  end
+
+## Runner#run
+#
+  def test_has_a_run_loop
+    assert{ build_runner.respond_to? :run }
+  end
+
+private
+
+  def build_runner
+    assert{ StableMatch::Runner.new( @set1 , @set2 ) }
+  end
+
+  def build_prepared_runner
+    runner = build_runner
+    assert{ runner.check! }
+    assert{ runner.build! }
+    runner
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: stable_match
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Ryan Cook
+- Ara Howard
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fattr
+  requirement: &70273026247540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *70273026247540
+- !ruby/object:Gem::Dependency
+  name: map
+  requirement: &70273026246260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 5.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70273026246260
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &70273026229780 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.12.1
+  type: :development
+  prerelease: false
+  version_requirements: *70273026229780
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70273026228300 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2.2
+  type: :development
+  prerelease: false
+  version_requirements: *70273026228300
+- !ruby/object:Gem::Dependency
+  name: rego
+  requirement: &70273026227040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *70273026227040
+description: A generic implementation of the stable match algorightm.
+email:
+- cookrn@gmail.com
+- ara.t.howard@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- examples/example_1.rb
+- lib/stable_match.rb
+- lib/stable_match/candidate.rb
+- lib/stable_match/runner.rb
+- lib/stable_match/version.rb
+- stable_match.gemspec
+- test/support/minitest.rb
+- test/test_helper.rb
+- test/unit/stable_match/candidate_test.rb
+- test/unit/stable_match/runner_test.rb
+homepage: https://github.com/cookrn/stable_match
+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: 4207718686449127189
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4207718686449127189
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.16
+signing_key: 
+specification_version: 3
+summary: stable_match v0.1.0
+test_files:
+- test/support/minitest.rb
+- test/test_helper.rb
+- test/unit/stable_match/candidate_test.rb
+- test/unit/stable_match/runner_test.rb