stable_match 0.1.1 → 0.2.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MWI3M2IwN2ZiZGJiYzcwZGIyMDcxOWY1MTViYmZiYzJhYTliMDJlZg==
+  data.tar.gz: !binary |-
+    NmMyZjk0MDI0NjA0NDZhOWE1M2Q2M2Y4NThmMGVmM2QyMzc4NTdiZg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NTAyNjhjYjgxYzYyN2E2ODZlOWE3NzFkODJhMjk2MmRkNWQ5MTE5Y2I4ZTlh
+    OWJmZmMwZTEyNmY3MjFlYTcxMWMzMmNjZGQ5MDc4ODZhZWFjMzI3YTRmYWUw
+    NTdiZjNiNWVmZGE1MGY4Y2JmNzY1NGUzNTM4YjIzNzQ5NGM5NDA=
+  data.tar.gz: !binary |-
+    ZTQ1MGIxZjQyZTZmOGY3ODBlOGFhNWEzNzVlMzkzMGExN2Y2ODkyOTU1M2Ix
+    Y2FkYTNlZTUyOWM5ZmNkNjUwODQwM2E1MGJmNWUzY2M1MmIxMzJiZTM0YzAy
+    ZDRjMzMyYmY1Yjc5N2MwNGY3YzgzZDE5ZmVjZDczMGMxNzJkOTU=

data/Gemfile

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

data/README.md

@@ -2,6 +2,52 @@
 
 A generic implementation of the Stable Match class of algorithms.
 
+## Usage
+
+* See: `examples/example_1.rb`
+* See: `test/functional/nrmp_test.rb`
+* See: `test/functional/stable_marriage_test.rb`
+* Run: `rake example`
+
+The idea behind stable matching is the following: You have two sets of
+data that you would like to find the most ideal matching between. Stable
+matching means that candidates from either set might remain unmatched.
+Unstable matching means that matches are forced even if they are not
+ideal.
+
+Your inputs are two hashes where the keys are known as 'target's to
+StableMatch. Targets ideally are domain specific objects to your
+application. The value in the hash for each target is an array of
+preferences for the target. (See the note below about when preferences
+are themselves each an Array object.)
+
+Preferences are an ordered array of 'target's belonging to the other set
+such that, the lower the index, the higher the preference. This is required
+and checked at runtime. It can be an empty array, but all preferences must
+belong to the other set.
+
+The final argument that a `Candidate` object can be instantiated with is
+called `match_positions` and equates to the number of matches that the
+given target can acquire. This is optional and defaults to 1.
+
+### In-Depth Example (IN PROGRESS)
+
+Let's talk about a dog-walker example. We have two domain classes: Dog
+and Walker. Let's say that the preferences will be determined by the
+weight and geographic location of the dog.
+
+```
+TODO !!
+FIXME !!
+this needs finished
+```
+
+### Gotchas
+
+* To match against objects that _are_ arrays, they'll need to be
+  preemptively wrapped in another array when passing them a runner. See
+  the NRMP test in `test/functional` for example.
+
 ## Installation
 
 ### Without Bundler
@@ -26,13 +72,6 @@ And then execute:
 $ bundle
 ```
 
-## Usage
-
-* See: `examples/example_1.rb`
-* Run: `rake example`
-
-TODO: Write more usage instructions here
-
 ## References
 
 * [http://halfamind.aghion.com/the-national-resident-matching-programs-nrmp](http://halfamind.aghion.com/the-national-resident-matching-programs-nrmp)

data/Rakefile

@@ -1,18 +1,36 @@
 #!/usr/bin/env rake
 
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 namespace :examples do
-  desc "Run any example"
+  desc 'Run any example'
+  task :all do
+    Dir[ "#{ File.dirname File.expand_path( __FILE__ ) }/examples/**/*.rb" ].each do | file |
+      puts
+      puts '============================================='
+      puts "Start Example: #{ file }"
+      puts '============================================='
+      puts
+      system "ruby #{ file }"
+      puts
+      puts '============================================='
+      puts "End Example: #{ file }"
+      puts '============================================='
+      puts
+    end
+  end
+
+  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"
+task :example  => 'examples:any'
+task :examples => 'examples:all'
 
 namespace :test do
-  desc "Run All The Tests"
+  desc 'Run All The Tests'
   task :all do
     suites = %w(
       test:functional
@@ -20,59 +38,36 @@ namespace :test do
     )
 
     suites.each do | suite |
-      puts "=========================================="
+      puts '=========================================='
       puts "Running: #{ suite }"
-      puts "=========================================="
+      puts '=========================================='
       begin
         Rake::Task[ suite ].invoke
       rescue
-        puts "=========================================="
+        puts '=========================================='
         puts "FAILED: #{ suite }"
       ensure
-        puts "=========================================="
+        puts '=========================================='
         puts "\n"
       end
     end
   end
 
-  desc "Run The Functional Tests"
+  desc 'Run The Functional Tests'
   Rake::TestTask.new( :functional ) do | t |
-    t.libs    << [ "test" ]
-    t.pattern = "test/functional/**/*_test.rb"
+    t.libs    << [ 'test' ]
+    t.pattern = 'test/functional/**/*_test.rb'
     t.verbose = true
   end
 
-  desc "Run The Unit Tests"
+  desc 'Run The Unit Tests'
   Rake::TestTask.new( :unit ) do | t |
-    t.libs    << [ "test" ]
-    t.pattern = "test/unit/**/*_test.rb"
+    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"
+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

@@ -4,21 +4,21 @@ class Test
 ## This is a modified version of the example NRMP case
 #
   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']}
+    'city'    => ['garcia', 'hassan', 'eastman', 'brown', 'chen', 'davis', 'ford'],
+    'general' => [ ['brown', 'eastman', 'hassan', 'anderson', 'chen', 'davis', 'garcia'] , 3 ],
+    'mercy'   => [ ['chen', 'garcia', 'brown'] , 2 ],
+    'state'   => ['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' ] }
+    'anderson' => ['state', 'city'],
+    'brown'    => ['city', 'mercy', 'state'],
+    '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' ]
   }
 
   def self.main

data/lib/stable_match.rb

@@ -1,12 +1,9 @@
-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"
+require 'stable_match/candidate'
+require 'stable_match/runner'
+require 'stable_match/version'

data/lib/stable_match/candidate.rb

@@ -1,45 +1,50 @@
+require 'yaml'
+require 'stable_match/util/initialize_with_defaults'
+
 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 )
+    include Util::InitializeWithDefaults
+
+    # The matches this candidate has attained
+    attr_accessor :matches
+
+    # The number of matches the candidate is able to make
+    attr_accessor :match_positions
+
+    # The tracked position for preferences that have been attempted for matches
+    attr_accessor :preference_position
+
+    # 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
+    attr_accessor :preferences
+
+    # The array to track proposals that have already been made
+    attr_accessor :proposals
+
+    # An ordered array of raw preference values
+    attr_accessor :raw_preferences
+
+    # The object that the candidate represents
+    attr_accessor :target
+
+    def initialize( target , raw_preferences , match_positions = 1 )
+      @target          = target
+      @raw_preferences = raw_preferences
+      @match_positions = 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 initialize_defaults!
+      @matches             ||= []
+      @preference_position ||= -1
+      @preferences         ||= []
+      @proposals           ||= []
+      @raw_preferences     ||= []
+    end
+
+    # 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
@@ -47,141 +52,106 @@ module StableMatch
       preference_index and match_preference_indexes.any? { |i| i > preference_index }
     end
 
-  ## Candidate#exhausted_preferences?
-  #
-  # Have all possible preferences been cycled through?
-  #
+    # 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`?
-  #
+    # 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
-  #
+    # 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
-    #
+      # 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?
-  #
+    # 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 )
+        'proposals'           => proposals.map( &:target ),
+        'raw_preferences'     => raw_preferences
       }.to_yaml
     end
 
-  ## Candidate#match!
-  #
-  # Match with another Candidate
-  #
-  # ARG: `other` -- another Candidate instance to match with
-  #
+    alias_method \
+      :pretty_inspect,
+      :inspect
+
+    # 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
-  #
+    # 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
-  #
+    # 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
-  #
+    # 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
-  #
+    # 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
-  #
+    # 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?
-      #
+        # Is there a preference for the candidate?
         when !prefers?( other )
           false
 
-      ## Are there available positions for more matches?
-      #
+        # Are there available positions for more matches?
         when free?
           match! other
 
-      ## Is the passed Candidate a better match than any other match?
-      #
+        # Is the passed Candidate a better match than any other match?
         when better_match?( other )
           free!
           match! other