matchy_matchy 0.1.0

data/lib/matchy_matchy/match_list.rb

@@ -0,0 +1,58 @@
+module MatchyMatchy
+  # A sorted list of matches with a strict capacity.
+  class MatchList
+    include Enumerable
+
+    # Initializes the list.
+    #
+    # @param capacity [Integer] The maximum number of matches this list can hold
+    def initialize(capacity = 1)
+      @matches = []
+      @capacity = capacity
+    end
+
+    # Pushes a match into the list.
+    # The list is re-sorted and any matches that don’t fit are rejected.
+    #
+    # @param match [MatchyMatchy::Match]
+    # @return [MatchyMatchy::MatchList] Self
+    def <<(match)
+      if include?(match)
+        match.reject!
+      else
+        @matches << match
+        @matches.sort!
+        @matches.pop.reject! if @matches.size > @capacity
+      end
+      self
+    end
+
+    # Returns true if the list contains the given match.
+    #
+    # @param match [MatchyMatchy::Match]
+    # @return [Boolean] True if the list contains this match already.
+    def include?(match)
+      any? { |m| m.eql?(match) }
+    end
+
+    # Returns an enumerator for the matches in the list.
+    # If a block is given, iterates through the matches in order, yielding them
+    # to the block.
+    #
+    # @yield [MatchyMatchy::Match]
+    # @return Enumerator
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      to_a.each(&block)
+    end
+
+    # Returns an array of the matches in the list.
+    #
+    # @return [Array]
+    def to_a
+      @matches.dup.freeze
+    end
+
+    alias to_ary to_a
+  end
+end

data/lib/matchy_matchy/match_results.rb

@@ -0,0 +1,53 @@
+module MatchyMatchy
+  # An object representing the results of the stable match algorithm.
+  class MatchResults
+    # A list of match targets.
+    attr_reader :targets
+
+    # A list of match candidates.
+    attr_reader :candidates
+
+    # Initializes the match results with an empty list of matches.
+    #
+    # @param targets [Array<MatchyMatchy::Target>] Array of all possible targets
+    # @param candidates [Array<MatchyMatchy::Candidate>
+    #   Array of all possible candidates
+    def initialize(targets:, candidates:)
+      @targets = targets
+      @candidates = candidates
+      @matches = targets.map { |t| [t, MatchList.new(t.capacity)] }.to_h
+    end
+
+    # Adds a match to the results.
+    #
+    # @param match [MatchyMatchy::Match] A match to add
+    # @return [MatchyMatchy::MatchResults] Self
+    def <<(match)
+      @matches[match.target] << match
+      self
+    end
+
+    # Returns a hash where the keys are the targets in the match, and the
+    # values are an ordered list of candidates for each target (if any).
+    # Targets are included even if no candidates could be matched there.
+    #
+    # @return [Hash<MatchyMatchy::Target, Array<MatchyMatchy::Candidate>>]
+    def by_target
+      targets.
+        map { |t| [t.object, @matches[t].map { |m| m.candidate.object }] }.
+        to_h.
+        freeze
+    end
+
+    # Returns a hash where the keys are the candidates in the match, and the
+    # values are the targets selected for each candidate (or nil, if the
+    # algorithm was unable to place the candidate).
+    #
+    # @return [Hash<MatchyMatchy::Target, Array<MatchyMatchy::Candidate>>]
+    def by_candidate
+      placements =
+        by_target.to_a.flat_map { |t, cs| cs.map { |c| [c, t] } }.to_h
+      candidates.map { |c| [c.object, placements[c.object]] }.to_h.freeze
+    end
+  end
+end

data/lib/matchy_matchy/matchbook.rb

@@ -0,0 +1,92 @@
+module MatchyMatchy
+  # Small class to maintain a cache of candidates and targets, for use by the
+  # +MatchMaker+. Ensures the following conditions:
+  #
+  # * Candidates and targets are kept separate, even if the objects they wrap
+  #   are identical
+  # * Exactly one +Candidate+ or +Target+ instance is created for each object
+  #   considered by the +MatchMaker+
+  # * Objects are not double-wrapped
+  class Matchbook
+    # Initializes the Matchbook with an empty cache.
+    def initialize
+      @targets = {}
+      @candidates = {}
+    end
+
+    # Builds a list of targets for the +MatchMaker+.
+    # The parameter is a hash of unwrapped target objects to their preferred
+    # candidates and maximum capacity (a 2-tuple expressed as an array):
+    #
+    # @example With explicit capacities
+    #   matchbook.build_targets(
+    #     'Gryffindor' => [['Hermione', 'Ron', 'Harry'], 2],
+    #     'Ravenclaw'  => [['Hermione'], 1],
+    #     'Hufflepuff' => [['Neville', 'Hermione'], 2],
+    #     'Slytherin'  => [['Harry', 'Hermione', 'Ron', 'Neville'], 4]
+    #   )
+    #
+    # The capacity may also be omitted, in which case it defaults to 1:
+    #
+    # @example With explicit capacities
+    #   matchbook.build_targets(
+    #     'Gryffindor' => ['Hermione', 'Ron', 'Harry'],
+    #     'Ravenclaw'  => ['Hermione'],
+    #     'Hufflepuff' => ['Neville', 'Hermione'],
+    #     'Slytherin'  => ['Harry', 'Hermione', 'Ron', 'Neville'],
+    #   )
+    #
+    # @param targets [Hash<Object, Array<Object>>]
+    #   Hash of target objects to a list of their preferred candidates
+    def build_targets(targets)
+      targets.to_a.map do |object, row|
+        preferences, capacity = parse_target_row(row)
+        target(object).tap do |t|
+          t.capacity = capacity
+          t.prefer(*preferences.map { |c| candidate(c) })
+        end
+      end
+    end
+
+    # Builds a list of candidates for the +MatchMaker+.
+    # The parameter is a hash of unwrapped canditate objects to their preferred
+    # targets.
+    #
+    # @example
+    #   matchbook.build_candidates(
+    #     'Harry'    => ['Gryffindor', 'Slytherin'],
+    #     'Hermione' => ['Ravenclaw', 'Gryffindor'],
+    #     'Ron'      => ['Gryffindor'],
+    #     'Neville'  => ['Hufflepuff', 'Gryffindor', 'Ravenclaw', 'Slytherin']
+    #   )
+    #
+    # @param candidates [Hash<Object, Array<Object>>]
+    #   Hash of candidate objects to a list of their preferred targets
+    def build_candidates(candidates)
+      candidates.to_a.map do |object, preferences|
+        candidate(object).tap do |c|
+          c.prefer(*preferences.map { |t| target(t) })
+        end
+      end
+    end
+
+    private
+
+    def target(object)
+      return object if object.is_a?(Target)
+      @targets[object] ||= Target.new(object)
+    end
+
+    def candidate(object)
+      return object if object.is_a?(Candidate)
+      @candidates[object] ||= Candidate.new(object)
+    end
+
+    def parse_target_row(row)
+      return row if row.size == 2 &&
+          row.first.respond_to?(:map) &&
+          row.last.respond_to?(:zero?)
+      [row, 1]
+    end
+  end
+end

data/lib/matchy_matchy/matchmaker.rb

@@ -0,0 +1,90 @@
+module MatchyMatchy
+  # Implements the Stable Match algorithm ovver a given set of candidates and
+  # targets.
+  class MatchMaker
+    # Initializes the MatchMaker.
+    # You must specify a list of +targets+ (objects “offering” places) and
+    # +candidates+ (objects “seeking” places). These can be any type of object:
+    # they are wrapped internally, but you should never have to deal with that.
+    #
+    # @example
+    #   match_maker = MatchyMatchy::MatchMaker.new(
+    #     targets: {
+    #       'Gryffindor' => [['Hermione', 'Ron', 'Harry'], 2],
+    #       'Ravenclaw'  => [['Hermione'], 1],
+    #       'Hufflepuff' => [['Neville', 'Hermione'], 2],
+    #       'Slytherin'  => [['Harry', 'Hermione', 'Ron', 'Neville'], 4]
+    #     },
+    #     candidates: {
+    #       'Harry'    => ['Gryffindor', 'Slytherin'],
+    #       'Hermione' => ['Ravenclaw', 'Gryffindor'],
+    #       'Ron'      => ['Gryffindor'],
+    #       'Neville'  => ['Hufflepuff', 'Gryffindor', 'Ravenclaw', 'Slytherin']
+    #     }
+    #   )
+    #
+    # The +target+ and +candidate+ parameters look similar, but the values in
+    # the +target+ hash have an extra number, which is the maximum capacity of
+    # that target (the total number of candidates it can accept). The capacity
+    # may also be omitted, in which case it defaults to 1; that is:
+    #
+    #   {
+    #     'Gryffindor' => ['Hermione', 'Ron', 'Harry'],
+    #     'Ravenclaw'  => ['Hermione'],
+    #     'Hufflepuff' => ['Neville', 'Hermione'],
+    #     'Slytherin'  => ['Harry', 'Hermione', 'Ron', 'Neville'],
+    #   }
+    #
+    # ...is equivalent to:
+    #
+    #   {
+    #     'Gryffindor' => [['Hermione', 'Ron', 'Harry'], 1],
+    #     'Ravenclaw'  => [['Hermione'], 1],
+    #     'Hufflepuff' => [['Neville', 'Hermione'], 1],
+    #     'Slytherin'  => [['Harry', 'Hermione', 'Ron', 'Neville'], 1]
+    #   }
+    def initialize(targets:, candidates:)
+      @matchbook = Matchbook.new
+      @targets = matchbook.build_targets(targets)
+      @candidates = matchbook.build_candidates(candidates)
+      @matches = MatchResults.new(targets: @targets, candidates: @candidates)
+    end
+
+    # Kicks off the match.
+    # Iterates through the candidates in order, proposing each to their
+    # first-choice target. If this match is rejected, the candidate is proposed
+    # to their next choice of candidate (if any).
+    #
+    # The running time of the algorithm is proportional to the number of
+    # candidates and targets in the system, but is guaranteed to finish and
+    # yield the same result for the same input.
+    #
+    # @return [MatchyMatchy::MatchResults] A +MatchResults+ object representing
+    #   the outcome of the algorithm.
+    def perform
+      candidates.each { |candidate| propose(candidate) }
+      @matches
+    end
+
+    private
+
+    attr_reader :matchbook, :targets, :candidates
+
+    def propose(candidate, index = 0)
+      return unless index < candidate.preferences.size
+
+      proposed = match(candidate, index)
+      if proposed.mutual?
+        @matches << proposed
+      else
+        proposed.reject!
+      end
+    end
+
+    def match(candidate, index)
+      Match.
+        new(candidate: candidate, index: index).
+        on(:reject) { propose(candidate, index + 1) }
+    end
+  end
+end

data/lib/matchy_matchy/target.rb

@@ -0,0 +1,17 @@
+module MatchyMatchy
+  # Represents a target in the Stable Match algorithm.
+  # A target is largely the same as a candidate, with the addition of the
+  # concept of “capacity”: how many candidates the target is willing to accept.
+  class Target < Candidate
+    attr_accessor :capacity
+
+    # Initializes the target with an object to wrap, and a capacity.
+    #
+    # @param object [Object] The object represented by this target
+    # @param capacity [Integer] The target’s maximum capacity
+    def initialize(object, capacity: 1)
+      super(object)
+      @capacity = capacity
+    end
+  end
+end

data/lib/matchy_matchy/version.rb

@@ -0,0 +1,3 @@
+module MatchyMatchy
+  VERSION = '0.1.0'.freeze
+end

data/matchy_matchy.gemspec

@@ -0,0 +1,29 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'matchy_matchy/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'matchy_matchy'
+  spec.version       = MatchyMatchy::VERSION
+  spec.authors       = ['Matt Powell']
+  spec.email         = ['fauxparse@gmail.com']
+
+  spec.summary       = 'A cute Stable Match implementation'
+  spec.homepage      = 'https://github.com/fauxparse/matchy_matchy'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'cry', '~> 0.1'
+
+  spec.add_development_dependency 'bundler', '~> 1.16.a'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec_junit_formatter', '~> 0.4.1'
+  spec.add_development_dependency 'simplecov'
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: matchy_matchy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matt Powell
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-09-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.16.a
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.16.a
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  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:
+- fauxparse@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".circleci/config.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/matchy_matchy.rb
+- lib/matchy_matchy/candidate.rb
+- lib/matchy_matchy/match.rb
+- lib/matchy_matchy/match_list.rb
+- lib/matchy_matchy/match_results.rb
+- lib/matchy_matchy/matchbook.rb
+- lib/matchy_matchy/matchmaker.rb
+- lib/matchy_matchy/target.rb
+- lib/matchy_matchy/version.rb
+- matchy_matchy.gemspec
+homepage: https://github.com/fauxparse/matchy_matchy
+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.5.2.3
+signing_key: 
+specification_version: 4
+summary: A cute Stable Match implementation
+test_files: []