xo 1.0.0 → 1.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NTMyNzA0ODhkYmI4OGE5ZjM3ZDc3YjZkNDA2NGQ0ZWZjMWI3ODYwYQ==
+    ZmU4ZmMyZTlhMjE5NWI1OWI1YmZmNGNjYjYwZTQwZjEzZGE3YzQxZQ==
   data.tar.gz: !binary |-
-    OWNlNjMxM2JmMDEzMTQ0YWJjNjdjMDUzYmQ0ZDQ3YmY3OWUzMDk4OA==
+    MzBlZDEyZDZlZjQyOTRjYzE3Mjc4NzA2NzBmNWU5Y2RlODU5OGQzZA==
 SHA512:
   metadata.gz: !binary |-
-    OGY3M2IyNWE0Y2YzYzZkMzlhMmEzNzIyODg3YTFiNzg1MzFiMjZkZDBiMjZl
-    OWMzYzllZjVhYTVjOWM1NTYxY2MyYWQ3ODdlZDhmNzUxMjNlNTA0N2VhYzQ2
-    MjE4OWJhNGE0NTk3YTFiYTU3MWViMjAxODcxZGQ0OGFiYjAwMGU=
+    MzNlNWQ2Zjg0ZjdjNjIzZGY1MWM3NDE5ZmM0ODNkMDU1ZDdlMWYxM2E3NWU4
+    MmQ3Zjk2ZGU3M2Q1YmFiMzZjZDgwMDcwY2RiY2VjMzA5ZjU5ZTNiM2U3MDM4
+    MWQyMzEzOGVmM2E1OTcwYWM5MWVmOWQ3YjE0MThiYWIyNWUzZGI=
   data.tar.gz: !binary |-
-    ZjllZDA0YzY0MDYzMTVlY2EzMzlkZmE4NjU2ZjEzNDYwOTJiM2EwNDYyNmI0
-    YTRlZWRlOWM0N2MyNjFkM2FhYmU0MTJlNzA5NDVhMjFmZjk0OTQ0NTMzYzYx
-    Yzk2ZjFmNzAyY2JlNzY0OWM3OTEyMTNkYjkyOTBiMTcwNGJjZDQ=
+    NjNhMzIyZTNjODgxNjE2Yzg0ZTk3ZDg1MjEzMjFhZTI4ZTdkYjExMWNjNDk3
+    ZjI0ZTQ5YmU5MDdhZjY3ZDRjMjI1Yjc0OGIwMWUzMDdhMGFhMGE1M2U0ODE0
+    ODcyZTllODk0NjQzY2RlYzFiMmQzODcyNjlmMzA1MTk4MDA0MmY=

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    xo (0.0.1)
+    xo (1.0.0)
+      state_design_pattern (~> 0.0.2)
 
 GEM
   remote: https://rubygems.org/
@@ -25,6 +26,7 @@ GEM
       multi_json
       simplecov-html (~> 0.8.0)
     simplecov-html (0.8.0)
+    state_design_pattern (0.0.2)
     term-ansicolor (1.3.0)
       tins (~> 1.0)
     thor (0.19.1)

data/README.md

@@ -5,11 +5,20 @@
 [![Coverage Status](https://coveralls.io/repos/dwayne/xo/badge.png)](https://coveralls.io/r/dwayne/xo)
 [![Code Climate](https://codeclimate.com/github/dwayne/xo.png)](https://codeclimate.com/github/dwayne/xo)
 
-A [Ruby](http://www.ruby-lang.org/en/) library for [Tic-tac-toe](http://en.wikipedia.org/wiki/Tic-tac-toe).
+A [Ruby](http://www.ruby-lang.org/en/) library for
+[Tic-tac-toe](http://en.wikipedia.org/wiki/Tic-tac-toe).
 
-The code is well documented and fully tested, so please have a [read of the documentation](http://rubydoc.info/github/dwayne/xo) and have a [look at the tests](https://github.com/dwayne/xo/tree/master/spec/xo).
+The code is well documented and fully tested, so please have a
+[read of the documentation](http://rubydoc.info/github/dwayne/xo) and have a
+[look at the tests](https://github.com/dwayne/xo/tree/master/spec/xo).
 
-My implementation of the [Minimax algorithm](http://en.wikipedia.org/wiki/Minimax#Minimax_algorithm_with_alternate_moves) might be a little different than what you've seen before. It uses symmetry to significantly reduce the search space and in so doing we get good [performance out of the algorithm](#Performance_of_the_Minimax_Algorithm). However, I still want to get it under 1 second. I'd love to get your thoughts on how I can make it happen. Have a [look](https://github.com/dwayne/xo/blob/master/lib/xo/ai/minimax.rb#L23).
+My implementation of the [Minimax algorithm](http://en.wikipedia.org/wiki/Minimax#Minimax_algorithm_with_alternate_moves)
+might be a little different than what you've seen before. It uses symmetry to
+significantly reduce the search space and in so doing we get good
+[performance out of the algorithm](#performance-of-the-minimax-algorithm).
+However, I still want to get it under 1 second. I'd love to hear your thoughts
+on how I can make it happen. Have a
+[look](https://github.com/dwayne/xo/blob/master/lib/xo/ai/minimax.rb#L23).
 
 ## Installation
 
@@ -23,7 +32,6 @@ Managing the grid yourself.
 
 ```ruby
 require 'xo'
-
 include XO
 
 g = Grid.new('xx oo')
@@ -34,10 +42,12 @@ puts g # =>  x | x |
        #    ---+---+---
        #       |   |
 
-Evaluator.analyze(g, Grid::X) # => { status: :ok }
+evaluator = Evaluator.instance
+
+evaluator.analyze(g, Grid::X) # => { status: :ok }
 
 g[1, 3] = Grid::X
-Evaluator.analyze(g, Grid::X) # => { status: :game_over,
+evaluator.analyze(g, Grid::X) # => { status: :game_over,
                               #      type: :winner,
                               #      details: [{
                               #        where: :row,
@@ -46,7 +56,7 @@ Evaluator.analyze(g, Grid::X) # => { status: :game_over,
                               #      }]
                               #    }
 
-Evaluator.analyze(g, Grid::O) # => { status: :game_over,
+evaluator.analyze(g, Grid::O) # => { status: :game_over,
                               #      type: :loser,
                               #      details: [{
                               #        where: :row,
@@ -56,32 +66,52 @@ Evaluator.analyze(g, Grid::O) # => { status: :game_over,
                               #    }
 ```
 
-The problem with managing the grid yourself is that there is nothing stopping you from making bad moves. For example, playing twice.
+The problem with managing the grid yourself is that there is nothing stopping
+you from making bad moves. For example, playing twice.
 
 ```ruby
 g = Grid.new('xx')
-Evaluator.analyze(g, Grid::O) # => { status: :invalid_grid,
+evaluator.analyze(g, Grid::O) # => { status: :invalid_grid,
                               #      type: :too_many_moves_ahead
                               #    }
 ```
 
-To avoid such situations, let the engine handle game play. Once you tell it who plays first, then it ensures that the game play follows the rules of [Tic-tac-toe](http://en.wikipedia.org/wiki/Tic-tac-toe).
+To avoid such situations, let the engine handle game play. Once you tell it who
+plays first, then it ensures that the game play follows the rules of
+[Tic-tac-toe](http://en.wikipedia.org/wiki/Tic-tac-toe).
 
 ```ruby
 e = Engine.new
+
+class EngineObserver
+
+  attr_reader :last_event
+
+  def update(event)
+    @last_event = event
+  end
+end
+
+observer = EngineObserver.new
+e.add_observer(observer)
+
 e.start(Grid::O).play(2, 1).play(1, 1).play(2, 2).play(1, 2).play(2, 3)
-e.last_event # => { name: :game_over,
-             #      type: :winner,
-             #      last_move: { turn: :o, r: 2, c: 3 },
-             #      details: [{
-             #        where: :row,
-             #        index: 2,
-             #        positions: [[2, 1], [2, 2], [2, 3]]
-             #      }]
-             #    }
+observer.last_event # => { name: :game_over,
+                    #      source: #<XO::Engine...>
+                    #      type: :winner,
+                    #      last_move: { turn: :o, r: 2, c: 3 },
+                    #      details: [{
+                    #        where: :row,
+                    #        index: 2,
+                    #        positions: [[2, 1], [2, 2], [2, 3]]
+                    #      }]
+                    #    }
 ```
 
-I also built a [Tic-tac-toe](http://en.wikipedia.org/wiki/Tic-tac-toe) command-line client that uses the library. See how everything comes together by viewing its implementation right [here](https://github.com/dwayne/xo/blob/master/bin/xo).
+I also built a [Tic-tac-toe](http://en.wikipedia.org/wiki/Tic-tac-toe)
+command-line client that uses the library. See how everything comes together by
+viewing its implementation right
+[here](https://github.com/dwayne/xo/blob/master/bin/xo).
 
 To use the [client](https://github.com/dwayne/xo/blob/master/bin/xo) just type,
 
@@ -110,11 +140,17 @@ You can run:
 
 ## Contributing
 
-If you'd like to contribute a feature or bugfix: Thanks! To make sure your fix/feature has a high chance of being included, please read the following guidelines:
+If you'd like to contribute a feature or bugfix: Thanks! To make sure your
+fix/feature has a high chance of being included, please read the following
+guidelines:
 
 1. Post a [pull request](https://github.com/dwayne/xo/compare/).
-2. Make sure there are tests! I will not accept any patch that is not tested. It's a rare time when explicit tests aren't needed. If you have questions about writing tests for xo, please open a [GitHub issue](https://github.com/dwayne/xo/issues/new).
+2. Make sure there are tests! I will not accept any patch that is not tested.
+   It's a rare time when explicit tests aren't needed. If you have questions
+   about writing tests for xo, please open a
+   [GitHub issue](https://github.com/dwayne/xo/issues/new).
 
 ## License
 
-xo is Copyright © 2014 Dwayne R. Crooks. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.
+xo is Copyright © 2014 Dwayne R. Crooks. It is free software, and may be
+redistributed under the terms specified in the MIT-LICENSE file.

data/bin/xo

@@ -168,46 +168,41 @@ class Game
 
   def initialize(players)
     @players = players
+
     @engine = Engine.new
+    @engine.add_observer(self)
   end
 
   def start(turn = false)
-    if turn
-      @engine.start(turn)
-    else
-      event = @engine.last_event
-
-      case event[:type]
-      when :winner
-        @engine.continue_playing(@engine.turn)
-      when :squashed
-        @engine.continue_playing(@engine.next_turn)
-      end
-    end
+    turn ? engine.start(turn) : engine.continue_playing
   end
 
   def run
-    run_one_turn while @engine.state != :game_over
+    run_one_turn until engine.current_state == GameOver
   end
 
-  private
+  def update(event)
+    player = players[engine.turn]
 
-    def run_one_turn
-      turn = @engine.turn
-      player = @players[turn]
+    case event[:name]
+    when :next_turn
+      player.handle_next_turn(engine.grid)
+    when :game_over
+      player.handle_game_over(engine.grid, event)
+    when :invalid_move
+      player.handle_invalid_move(event)
+    end
+  end
 
-      r, c = player.get_move(@engine.grid, turn)
+  private
 
-      event = @engine.play(r, c).last_event
+    attr_reader :players, :engine
 
-      case event[:name]
-      when :next_turn
-        player.handle_next_turn(@engine.grid)
-      when :game_over
-        player.handle_game_over(@engine.grid, event)
-      when :invalid_move
-        player.handle_invalid_move(event)
-      end
+    def run_one_turn
+      turn = engine.turn
+      r, c = players[turn].get_move(engine.grid, turn)
+
+      engine.play(r, c)
     end
 end
 

data/lib/xo.rb

@@ -1,4 +1,4 @@
 require 'xo/grid'
 require 'xo/evaluator'
 require 'xo/engine'
-require 'xo/ai'
+require 'xo/ai/minimax'

data/lib/xo/ai/max_player.rb

@@ -0,0 +1,22 @@
+require 'xo/ai/player'
+
+module XO
+
+  module AI
+
+    class MaxPlayer < Player
+
+      def best_score(next_grids_scores)
+        next_grids_scores.max
+      end
+
+      def winner_value
+        1
+      end
+
+      def loser_value
+        -1
+      end
+    end
+  end
+end

data/lib/xo/ai/min_player.rb

@@ -0,0 +1,22 @@
+require 'xo/ai/player'
+
+module XO
+
+  module AI
+
+    class MinPlayer < Player
+
+      def best_score(next_grids_scores)
+        next_grids_scores.min
+      end
+
+      def winner_value
+        -1
+      end
+
+      def loser_value
+        1
+      end
+    end
+  end
+end

data/lib/xo/ai/minimax.rb

@@ -2,6 +2,8 @@ require 'singleton'
 
 require 'xo/evaluator'
 require 'xo/ai/geometric_grid'
+require 'xo/ai/min_player'
+require 'xo/ai/max_player'
 
 module XO
 
@@ -14,49 +16,13 @@ module XO
     # The search space forms a tree where the root is the empty grid and every other node is a possible grid configuration that
     # can be reached by playing through a game of Tic-tac-toe.
     #
-    # Given any node in the tree and an indication of whose turn it is to play next, all the node's children can be determined by
-    # making one move in each of its open positions. For example, given the node
-    #
-    #    x | o | x
-    #   ---+---+---
-    #      | x |
-    #   ---+---+---
-    #    o |   | o
-    #
-    # and knowing that it's {XO::Grid::O}'s (the min player) turn to play. Then, its children will be the 3 nodes
-    #
-    #        A             B             C
-    #
-    #    x | o | x     x | o | x     x | o | x
-    #   ---+---+---   ---+---+---   ---+---+---
-    #    o | x |         | x | o       | x |
-    #   ---+---+---   ---+---+---   ---+---+---
-    #    o |   | o     o |   | o     o | o | o
-    #
-    # since there are 3 open positions in which {XO::Grid::O} can make a move.
-    #
-    # Within the implementation, A and B will be considered intermediate nodes and so the search algorithm will have to continue until
-    # it can make a conclusive determination. That occurs when it reaches a terminal node, like C. In that case, the algorithm assigns
-    # a value to the terminal node from the perspective of the player that has to play next. So in C's case,
-    # {XO::Grid::X} (the max player) has to play next. But {XO::Grid::X} can't play because {XO::Grid::O} won. So {XO::Grid::X} would
-    # value C with a low value, -1 in this case.
-    #
-    # Each intermediate node can now get a value in the following way. Consider node A. It's {XO::Grid::X}'s turn to play and
-    # {XO::Grid::X} is the max player. The max player seeks to maximize their value over all the values of its children (conversely,
-    # the min player seeks to minimize their value over all its children). It has 2 children and they will eventually be determined
-    # to have the values 0 and -1. Since 0 is greater than -1, A will get the value of 0. What this means essentially is that the max
-    # player will play to favor a squashed game rather than a losing game in this particular instance.
-    #
-    # It is interesting to note that B is simply a reflection of A and so will end up having the same value. The algorithm below is
-    # smart enough to recognize that and so it will not have to perform a similar calculation in B's case.
-    #
-    # The Minimax class is a Singleton class. You use it as follows:
+    # {Minimax} is a Singleton which can be used as follows:
     #
     # @example
     #  Minimax.instance.moves(XO::Grid.new('xox x o o'), XO::Grid::O) # => [[3, 2]]
     #
     # The first time the instance of Minimax is created, it runs the minimax algorithm to compute the value of all the nodes in the
-    # search space. This of course takes a bit of time (~ 4 seconds), but subsequent calls are instantaneous.
+    # search space. This of course takes a bit of time (~ 4 seconds), but subsequent calls are super fast.
     class Minimax
       include Singleton
 
@@ -67,14 +33,21 @@ module XO
       # @raise [ArgumentError] if turn is not a token or the combination of the values of grid and turn doesn't make sense
       # @return [Array<Array(Integer, Integer)>]
       def moves(grid, turn)
-        raise ArgumentError, "illegal token #{turn}" unless GeometricGrid.is_token?(turn)
-
-        best_moves(*lift(grid, turn))
+        check_turn(turn)
+        best_moves(*normalize(grid, turn))
       end
 
       private
 
-        attr_reader :the_grid, :scores
+        attr_reader :master_grid, :scores
+
+        X = GeometricGrid::X
+        O = GeometricGrid::O
+
+        EMPTY = GeometricGrid::EMPTY
+
+        MAX_PLAYER = MaxPlayer.new(X)
+        MIN_PLAYER = MinPlayer.new(O)
 
         def initialize
           init_search
@@ -82,74 +55,74 @@ module XO
         end
 
         def init_search
-          @the_grid = GeometricGrid.new
-          @scores = {}
+          @master_grid = GeometricGrid.new
+          @scores      = {}
         end
 
-        def build_search_tree(player = MaxPlayer)
+        def build_search_tree(player_a = MAX_PLAYER, player_b = MIN_PLAYER)
           return if has_score?
 
-          analyze_grid(player)
+          analyze_grid(player_a)
 
           if terminal?
-            set_score(player)
+            set_terminal_score(player_a)
           else
             next_grids = []
 
-            the_grid.each_open do |r, c|
-              the_grid[r, c] = player.token
-              next_grids << the_grid.dup
+            master_grid.each_open do |r, c|
+              master_grid[r, c] = player_a.token
+              next_grids << master_grid.dup
 
-              build_search_tree(player.other)
+              build_search_tree(player_b, player_a)
 
-              the_grid[r, c] = :e
+              master_grid[r, c] = EMPTY
             end
 
-            set_final_score(player, next_grids)
+            set_non_terminal_score(player_a, next_grids)
           end
         end
 
         def has_score?
-          scores.key?(the_grid)
+          scores.key?(master_grid)
         end
 
         def analyze_grid(player)
-          @results = Evaluator.instance.analyze(the_grid, player.token)
+          @result = Evaluator.instance.analyze(master_grid, player.token)
         end
 
         def terminal?
-          @results[:status] == :game_over
+          @result[:status] == :game_over
         end
 
-        def set_score(player)
-          scores[the_grid.dup] = player.score(@results[:type])
+        def set_terminal_score(player)
+          scores[master_grid.dup] = player.terminal_score(@result[:type])
         end
 
-        def set_final_score(player, next_grids)
-          scores[the_grid.dup] = player.final_score(next_grids, scores)
+        def set_non_terminal_score(player, next_grids)
+          scores[master_grid.dup] = player.non_terminal_score(next_grids, scores)
         end
 
-        # The search tree that gets built is for the situation when {XO::Grid::X} is assumed to
+        # The search tree that gets built is for the situation when X is assumed to
         # have played first. However, if we are given a grid to evaluate such that
-        # it can only be reached by assuming that {XO::Grid::O} played first then we need to
+        # it can only be reached by assuming that O played first then we need to
         # patch things up so that we can find a representative in our search space
         # for the given configuration.
-        def lift(grid, turn)
-          xs, os = Evaluator.instance.xos(grid)
+        def normalize(grid, turn)
+          xs, os = Evaluator.xos(grid)
 
-          if turn == GeometricGrid::X
+          if turn == X
             if xs == os
-              [GeometricGrid.new(grid.inspect), GeometricGrid::X]
+              [GeometricGrid.new(grid.inspect), X]
             elsif xs < os
-              [invert(grid), GeometricGrid::O]
+              [invert(grid), O]
             else
               raise ArgumentError, "#{grid} and #{turn} is not a valid combination, too many X's"
             end
           else
             if xs == os
-              [invert(grid), GeometricGrid::X]
+              [invert(grid), X]
             elsif xs > os
-              [GeometricGrid.new(grid.inspect), GeometricGrid::O]
+              [GeometricGrid.new(grid.inspect), O]
             else
               raise ArgumentError, "#{grid} and #{turn} is not a valid combination, too many O's"
             end
@@ -166,6 +139,10 @@ module XO
           inverted_grid
         end
 
+        def check_turn(turn)
+          raise ArgumentError, "illegal token #{turn}" unless GeometricGrid.is_token?(turn)
+        end
+
         def best_moves(grid, turn)
           final_score = @scores[grid]
           moves = []
@@ -175,49 +152,11 @@ module XO
 
             moves << [r, c] if @scores[grid] == final_score
 
-            grid[r, c] = :e
+            grid[r, c] = EMPTY
           end
 
           moves
         end
     end
-
-    module MaxPlayer
-
-      def self.token
-        GeometricGrid::X
-      end
-
-      def self.other
-        MinPlayer
-      end
-
-      def self.score(type)
-        { winner: 1, loser: -1, squashed: 0 }[type]
-      end
-
-      def self.final_score(next_grids, scores)
-        next_grids.map { |grid| scores[grid] }.max
-      end
-    end
-
-    module MinPlayer
-
-      def self.token
-        GeometricGrid::O
-      end
-
-      def self.other
-        MaxPlayer
-      end
-
-      def self.score(type)
-        { winner: -1, loser: 1, squashed: 0 }[type]
-      end
-
-      def self.final_score(next_grids, scores)
-        next_grids.map { |grid| scores[grid] }.min
-      end
-    end
   end
 end