xo 1.0.0 → 1.1.0

data/lib/xo/evaluator.rb

@@ -4,25 +4,18 @@ require 'xo/grid'
 
 module XO
 
-  # This class defines an {Evaluator#analyze} method than can be used to look at a grid and
-  # answer the following questions:
+  # {Evaluator} is a {http://en.wikipedia.org/wiki/Singleton_pattern Singleton} that defines an {#analyze} method than can be used to examine a grid to answer the following questions:
   #
-  # 1. Is it a valid grid? A grid is considered valid if it possible for
-  #    two players, taking turns, to reach the given grid configuration.
+  # 1. Is it a valid grid? A grid is considered valid if it possible for two players, taking turns, to reach the given grid configuration.
   # 2. Is there a winner/loser or is the grid squashed?
   # 3. Who is the winner/loser?
   # 4. Which positions make up the winning row, column and/or diagonal?
-  #
-  # The Evaluator class is a Singleton class and can be used as follows:
-  #
-  # @example
-  #  Evaluator.instance.analyze(Grid.new('xo'), Grid::X)
   class Evaluator
     include Singleton
 
-    # Analyze a given grid assuming that the given token is the one that was last placed on it.
+    # Examines the given grid assuming that the given token is the one that was last placed on it.
     #
-    # It can return a hash in following formats:
+    # The following return values are possible:
     #
     # - If everything is fine, then
     #
@@ -30,11 +23,11 @@ module XO
     #
     # - If the game is over and the given token is in a winning position, then
     #
-    #     { status: :game_over, type: :winner, details: [{ where: :a_where, index: :an_index, positions: :the_positions }] }
+    #     { status: :game_over, type: :winner, details: [{ where: :where, index: :index, positions: :positions }] }
     #
     # - If the game is over and the other token is in a winning position, then
     #
-    #     { status: :game_over, type: :loser, details: [{ where: :a_where, index: :an_index, positions: :the_positions }] }
+    #     { status: :game_over, type: :loser, details: [{ where: :where, index: :index, positions: :positions }] }
     #
     # - If the game is over due to a squashed grid, then
     #
@@ -48,14 +41,13 @@ module XO
     #
     #     { status: :invalid_grid, type: :two_winners }
     #
-    # Legend:
+    # *Legend:*
     #
-    # - :a_where is one of :row, :column, :diagonal
-    # - :an_index is one of 1, 2, 3 if :a_where is :row or :column and one of 1, 2 if :a_where is :diagonal
-    # - :the_positions is a 3 element array having the row, column values of the winning position
+    # - *:where* is one of :row, :column, :diagonal
+    # - *:index* is one of 1, 2, 3 if :where is :row or :column and one of 1, 2 if :where is :diagonal
+    # - *:positions* is a 3 element array having the row, column values of the winning position
     #
-    # Notice that the :details key is an array since it is possible to win a game in two different ways. For
-    # example:
+    # Notice that the :details key is an Array since it is possible to win a game in two different ways. For example:
     #
     #    x | o | x
     #   ---+---+---
@@ -63,15 +55,13 @@ module XO
     #   ---+---+---
     #    x | o | x
     #
-    #   # Position (2, 2) would have to be the last position played for this to happen.
-    #
-    # @param grid [Grid] the grid to be analyzed
+    # @param grid [Grid] the grid to be examined
     # @param token [Grid::X, Grid::O] the token that was last placed on the grid
     # @raise [ArgumentError] unless token is either {Grid::X} or {Grid::O}
     # @return [Hash]
     def analyze(grid, token)
       check_token(token)
-      init_analyzer(grid, token)
+      initialize_analyzer(grid, token)
       perform_analysis
     end
 
@@ -79,17 +69,17 @@ module XO
     #
     # @example
     #  g = Grid.new('xoxxo')
-    #  xs, os = Evaluator.instance.xos(g)
+    #  xs, os = Evaluator.xos(g)
     #  puts xs # => 3
     #  puts os # => 2
     #
     # @return [Array(Integer, Integer)]
-    def xos(grid)
+    def self.xos(grid)
       xs = os = 0
 
-      grid.each do |_, _, val|
-        xs += 1 if val == Grid::X
-        os += 1 if val == Grid::O
+      grid.each do |_, _, k|
+        xs += 1 if k == Grid::X
+        os += 1 if k == Grid::O
       end
 
       [xs, os]
@@ -103,30 +93,22 @@ module XO
         raise ArgumentError, "illegal token #{token}" unless Grid.is_token?(token)
       end
 
-      def init_analyzer(grid, token)
-        @grid = grid
-        @token = token
+      def initialize_analyzer(grid, token)
+        @grid    = grid
+        @token   = token
         @winners = {}
       end
 
       def perform_analysis
-        return { status: :invalid_grid, type: :too_many_moves_ahead } if two_or_more_moves_ahead?
+        return { status: :invalid_grid, type: :too_many_moves_ahead }              if two_or_more_moves_ahead?
 
         find_winners
 
-        if two_winners?
-          { status: :invalid_grid, type: :two_winners }
-        elsif winners[token]
-          { status: :game_over, type: :winner, details: winners[token] }
-        elsif winners[other_token]
-          { status: :game_over, type: :loser, details: winners[other_token] }
-        else
-          if grid.full?
-            { status: :game_over, type: :squashed }
-          else
-            { status: :ok }
-          end
-        end
+        return { status: :invalid_grid, type: :two_winners }                       if two_winners?
+        return { status: :game_over, type: :winner, details: winners[token] }      if winners[token]
+        return { status: :game_over, type: :loser, details: winners[other_token] } if winners[other_token]
+        return { status: :game_over, type: :squashed }                             if grid.full?
+        return { status: :ok }
       end
 
       def two_or_more_moves_ahead?
@@ -134,34 +116,32 @@ module XO
       end
 
       def moves_ahead
-        xs, os = xos(grid)
+        xs, os = self.class.xos(grid)
 
         (xs - os).abs
       end
 
-      def find_winners
-        winning_positions.each do |w|
-          a = grid[*w[:positions][0]]
-          b = grid[*w[:positions][1]]
-          c = grid[*w[:positions][2]]
+      WINNING_POSITIONS = [
+        { where: :row,      index: 1, positions: [[1, 1], [1, 2], [1, 3]] },
+        { where: :row,      index: 2, positions: [[2, 1], [2, 2], [2, 3]] },
+        { where: :row,      index: 3, positions: [[3, 1], [3, 2], [3, 3]] },
 
-          add_winner(a, w) if Grid.is_token?(a) && a == b && b == c
-        end
-      end
+        { where: :column,   index: 1, positions: [[1, 1], [2, 1], [3, 1]] },
+        { where: :column,   index: 2, positions: [[1, 2], [2, 2], [3, 2]] },
+        { where: :column,   index: 3, positions: [[1, 3], [2, 3], [3, 3]] },
 
-      def winning_positions
-        @winning_positions ||= [
-          { where: :row, index: 1, positions: [[1, 1], [1, 2], [1, 3]] },
-          { where: :row, index: 2, positions: [[2, 1], [2, 2], [2, 3]] },
-          { where: :row, index: 3, positions: [[3, 1], [3, 2], [3, 3]] },
+        { where: :diagonal, index: 1, positions: [[1, 1], [2, 2], [3, 3]] },
+        { where: :diagonal, index: 2, positions: [[1, 3], [2, 2], [3, 1]] }
+      ]
 
-          { where: :column, index: 1, positions: [[1, 1], [2, 1], [3, 1]] },
-          { where: :column, index: 2, positions: [[1, 2], [2, 2], [3, 2]] },
-          { where: :column, index: 3, positions: [[1, 3], [2, 3], [3, 3]] },
+      def find_winners
+        WINNING_POSITIONS.each do |w|
+          x = grid[*w[:positions][0]]
+          y = grid[*w[:positions][1]]
+          z = grid[*w[:positions][2]]
 
-          { where: :diagonal, index: 1, positions: [[1, 1], [2, 2], [3, 3]] },
-          { where: :diagonal, index: 2, positions: [[1, 3], [2, 2], [3, 1]] }
-        ]
+          add_winner(x, w.dup) if winning_combination(x, y, z)
+        end
       end
 
       def add_winner(token, details)
@@ -172,8 +152,12 @@ module XO
         end
       end
 
+      def winning_combination(x, y, z)
+        Grid.is_token?(x) && x == y && y == z
+      end
+
       def two_winners?
-        winners[Grid::X] && winners[Grid::O]
+        winners.keys.length == 2
       end
 
       def other_token

data/lib/xo/grid.rb

@@ -12,103 +12,54 @@ module XO
   #    2    |   |
   #      ---+---+---
   #    3    |   |
-  #
-  # It is important to note that if a position stores anything other than
-  # {X} or {O} then that position is considered to be open.
   class Grid
 
     X = :x
     O = :o
 
+    EMPTY = :e
+
     ROWS = 3
     COLS = 3
 
     N = ROWS * COLS
 
-    # Determines whether or not position (r, c) is such that 1 <= r <= 3 and 1 <= c <= 3.
-    #
-    # @param r [Integer] the row
-    # @param c [Integer] the column
-    # @return [Boolean] true iff the position is contained within a 3x3 grid
     def self.contains?(r, c)
       r.between?(1, ROWS) && c.between?(1, COLS)
     end
 
-    # Classifies what is and isn't considered to be a token.
-    #
-    # @param val [Object]
-    # @return [Boolean] true iff val is {X} or {O}
-    def self.is_token?(val)
-      val == X || val == O
+    def self.is_token?(k)
+      k == X || k == O
     end
 
-    # Determines the other token.
-    #
-    # @param val [Object]
-    # @return [Object] {X} given {O}, {O} given {X} or the original value
-    def self.other_token(val)
-      val == X ? O : (val == O ? X : val)
+    def self.other_token(k)
+      k == X ? O : (k == O ? X : k)
     end
 
-    attr_reader :grid
-    private :grid
-
-    # Creates a new empty grid by default. You can also create a
-    # prepopulated grid by passing in a string representation.
-    #
-    # @example
-    #  g = Grid.new('xo ox   o')
     def initialize(g = '')
       @grid = from_string(g)
     end
 
-    # Creates a copy of the given grid. Use #dup to get your copy.
-    #
-    # @example
-    #  g = Grid.new
-    #  g_copy = g.dup
-    #
-    # @param orig [Grid] the original grid
-    # @return [Grid] a copy
     def initialize_copy(orig)
       @grid = orig.instance_variable_get(:@grid).dup
     end
 
-    # Determines whether or not there are any tokens on the grid.
-    #
-    # @return [Boolean] true iff there are no tokens on the grid
     def empty?
-      grid.all? { |val| !self.class.is_token?(val) }
+      grid.all? { |k| !self.class.is_token?(k) }
     end
 
-    # Determines whether or not every position on the grid has a token?
-    #
-    # @return [Boolean] true iff every position on the grid has a token
     def full?
-      grid.all? { |val| self.class.is_token?(val) }
+      grid.all? { |k| self.class.is_token?(k) }
     end
 
-    # Sets position (r, c) to the given value.
-    #
-    # @param r [Integer] the row
-    # @param c [Integer] the column
-    # @param val [Object]
-    # @raise [IndexError] if the position is off the grid
-    # @return [Object] the value it was given
-    def []=(r, c, val)
+    def []=(r, c, k)
       if self.class.contains?(r, c)
-        grid[idx(r, c)] = self.class.is_token?(val) ? val : :e
+        grid[idx(r, c)] = normalize(k)
       else
         raise IndexError, "position (#{r}, #{c}) is off the grid"
       end
     end
 
-    # Retrieves the value at the given position (r, c).
-    #
-    # @param r [Integer] the row
-    # @param c [Integer] the column
-    # @raise [IndexError] if the position is off the grid
-    # @return [Object]
     def [](r, c)
       if self.class.contains?(r, c)
         grid[idx(r, c)]
@@ -117,29 +68,20 @@ module XO
       end
     end
 
-    # Determines whether or not position (r, c) contains a token.
-    #
-    # @param r [Integer] the row
-    # @param c [Integer] the column
-    # @raise [IndexError] if the position is off the grid
-    # @return true iff the position does not contain a token
     def open?(r, c)
       !self.class.is_token?(self[r, c])
     end
 
-    # Removes all tokens from the grid.
     def clear
-      grid.fill(:e)
-
-      self
+      grid.fill(EMPTY)
     end
 
-    # Used for iterating over all the positions of the grid from left to right and top to bottom.
+    # Iterates over all the positions of this grid from left to right and top to bottom.
     #
     # @example
     #  g = Grid.new
-    #  g.each do |r, c, val|
-    #    puts "(#{r}, #{c}) -> #{val}"
+    #  g.each do |r, c, k|
+    #    puts "(#{r}, #{c}) -> #{k}"
     #  end
     def each
       (1..ROWS).each do |r|
@@ -149,7 +91,7 @@ module XO
       end
     end
 
-    # Used for iterating over all the open positions of the grid from left to right and top to bottom.
+    # Iterates over all the open positions of this grid from left to right and top to bottom.
     #
     # @example
     #  g = Grid.new
@@ -164,16 +106,14 @@ module XO
       self.each { |r, c, _| yield(r, c) if open?(r, c) }
     end
 
-    # Returns a string representation of the grid which may be useful
-    # for debugging.
+    # Returns a string representation of this grid which can be useful for debugging.
     def inspect
-      grid.map { |val| t(val) }.join
+      grid.map { |k| t(k) }.join
     end
 
-    # Returns a string representation of the grid which may be useful
-    # for display.
+    # Returns a string representation of this grid which can be useful for display.
     def to_s
-      g = grid.map { |val| t(val) }
+      g = grid.map { |k| t(k) }
 
       [" #{g[0]} | #{g[1]} | #{g[2]} ",
        "---+---+---",
@@ -184,21 +124,23 @@ module XO
 
     private
 
-      def from_string(g)
-        g = g.to_s
-        l = g.length
+      attr_reader :grid
 
-        g = if l < N
-          g + ' ' * (N - l)
-        elsif l > N
-          g[0..N-1]
-        else
-          g
+      def from_string(s)
+        adjust_length(s, N).split('').map do |ch|
+          normalize(ch.to_sym)
         end
+      end
+
+      def adjust_length(s, n)
+        l = s.length
 
-        g.split('').map do |ch|
-          sym = ch.to_sym
-          sym == X || sym == O ? sym : :e
+        if l < n
+          s + ' ' * (n - l)
+        elsif l > n
+          s[0..n-1]
+        else
+          s
         end
       end
 
@@ -217,8 +159,14 @@ module XO
         COLS * (r - 1) + (c - 1)
       end
 
-      def t(val)
-        self.class.is_token?(val) ? val : ' '
+      NORMALIZED_TO_STRING_MAP = { X => 'x', O => 'o', EMPTY => ' ' }
+
+      def t(k)
+        NORMALIZED_TO_STRING_MAP[normalize(k)]
+      end
+
+      def normalize(k)
+        self.class.is_token?(k) ? k : EMPTY
       end
   end
 end

data/lib/xo/version.rb

@@ -1,3 +1,3 @@
 module XO
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/spec/engine_spec.rb

@@ -0,0 +1,323 @@
+require 'spec_helper'
+
+class EngineObserver
+
+  def initialize
+    @events = []
+  end
+
+  def last_event
+    @events.last
+  end
+
+  def update(event)
+    @events << event
+  end
+end
+
+module XO
+
+  describe Engine do
+
+    let (:engine) { Engine.new }
+    let (:engine_observer) { EngineObserver.new }
+
+    describe "how the engine works" do
+
+      before { engine.add_observer(engine_observer) }
+
+      describe "in the Init state" do
+
+        it "is in the Init state" do
+          engine.current_state.must_equal Init
+        end
+
+        describe "#start" do
+
+          describe "for valid input" do
+
+            before { engine.start(Grid::X) }
+
+            it "is X's turn" do
+              engine.turn.must_equal Grid::X
+            end
+
+            it "has an empty grid" do
+              engine.grid.must_be :empty?
+            end
+
+            it "transitions to the Playing state" do
+              engine.current_state.must_equal Playing
+            end
+
+            it "triggers an event" do
+              engine_observer.last_event[:name].must_equal :game_started
+            end
+          end
+
+          describe "for invalid input" do
+
+            it "raises ArgumentError" do
+              proc { engine.start(:nobody) }.must_raise ArgumentError
+            end
+          end
+        end
+
+        it "raises StateDesignPattern::IllegalStateException for the actions stop, play and continue_playing" do
+          proc { engine.stop }.must_raise StateDesignPattern::IllegalStateException
+          proc { engine.play(1, 1) }.must_raise StateDesignPattern::IllegalStateException
+          proc { engine.continue_playing(Grid::X) }.must_raise StateDesignPattern::IllegalStateException
+        end
+      end
+
+      describe "in the Playing state" do
+
+        before { engine.start(Grid::O) }
+
+        it "is in the Playing state" do
+          engine.current_state.must_equal Playing
+        end
+
+        describe "#play" do
+
+          describe "when the move is out of bounds" do
+
+            before { engine.play(1, 0) }
+
+            it "remains in the Playing state" do
+              engine.current_state.must_equal Playing
+            end
+
+            it "triggers an event" do
+              last_event = engine_observer.last_event
+
+              last_event[:name].must_equal :invalid_move
+              last_event[:type].must_equal :out_of_bounds
+            end
+          end
+
+          describe "when the move is on an occupied position" do
+
+            before { engine.play(1, 1).play(1, 1) }
+
+            it "remains in the Playing state" do
+              engine.current_state.must_equal Playing
+            end
+
+            it "triggers an event" do
+              last_event = engine_observer.last_event
+
+              last_event[:name].must_equal :invalid_move
+              last_event[:type].must_equal :occupied
+            end
+          end
+
+          describe "when the move results in a win" do
+
+            before do
+              engine.play(1, 1).play(2, 1).play(1, 2).play(2, 2).play(1, 3)
+            end
+
+            it "transitions to the GameOver state" do
+              engine.current_state.must_equal GameOver
+            end
+
+            it "triggers an event" do
+              last_event = engine_observer.last_event
+
+              last_event[:name].must_equal :game_over
+              last_event[:type].must_equal :winner
+              last_event[:last_move].must_equal({ turn: Grid::O, r: 1, c: 3 })
+              last_event[:details][0][:where].must_equal :row
+              last_event[:details][0][:index].must_equal 1
+            end
+          end
+
+          describe "when the move results in a squashed game" do
+
+            before do
+              engine
+                .play(1, 1).play(2, 2)
+                .play(3, 3).play(1, 2)
+                .play(3, 2).play(3, 1)
+                .play(1, 3).play(2, 3)
+                .play(2, 1)
+            end
+
+            it "transitions to the GameOver state" do
+              engine.current_state.must_equal GameOver
+            end
+
+            it "triggers an event" do
+              last_event = engine_observer.last_event
+
+              last_event[:name].must_equal :game_over
+              last_event[:type].must_equal :squashed
+              last_event[:last_move].must_equal({ turn: Grid::O, r: 2, c: 1 })
+            end
+          end
+
+          describe "when the move just advances the game" do
+
+            before { engine.play(1, 1) }
+
+            it "sets O at position (1, 1)" do
+              engine.grid[1, 1].must_equal Grid::O
+            end
+
+            it "remains in the Playing state" do
+              engine.current_state.must_equal Playing
+            end
+
+            it "triggers an event" do
+              last_event = engine_observer.last_event
+
+              last_event[:name].must_equal :next_turn
+              last_event[:last_move].must_equal({ turn: Grid::O, r: 1, c: 1 })
+            end
+          end
+        end
+
+        describe "#stop" do
+
+          before { engine.play(2, 2).play(3, 1).stop }
+
+          it "resets the game" do
+            engine.turn.must_equal :nobody
+            engine.grid.must_be :empty?
+          end
+
+          it "transitions to the Init state" do
+            engine.current_state.must_equal Init
+          end
+
+          it "triggers an event" do
+            engine_observer.last_event[:name].must_equal :game_stopped
+          end
+        end
+
+        it "raises StateDesignPattern::IllegalStateException for the actions start and continue_playing" do
+          proc { engine.start(Grid::X) }.must_raise StateDesignPattern::IllegalStateException
+          proc { engine.continue_playing(Grid::X) }.must_raise StateDesignPattern::IllegalStateException
+        end
+      end
+
+      describe "in the GameOver state" do
+
+        describe "due to a win" do
+
+          before do
+            engine
+              .start(Grid::X)
+              .play(1, 1).play(2, 1).play(1, 2).play(2, 2).play(1, 3)
+          end
+
+          it "is in the GameOver state" do
+            engine.current_state.must_equal GameOver
+          end
+
+          describe "#continue_playing" do
+
+            before { engine.continue_playing }
+
+            it "is X's turn" do
+              engine.turn.must_equal Grid::X
+            end
+
+            it "has an empty grid" do
+              engine.grid.must_be :empty?
+            end
+
+            it "transitions to the Playing state" do
+              engine.current_state.must_equal Playing
+            end
+
+            it "triggers an event" do
+              last_event = engine_observer.last_event
+
+              last_event[:name].must_equal :game_started
+              last_event[:type].must_equal :continue_playing
+            end
+          end
+        end
+
+        describe "due to a squashed game" do
+
+          before do
+            engine
+              .start(Grid::X)
+              .play(1, 1).play(2, 2)
+              .play(3, 3).play(1, 2)
+              .play(3, 2).play(3, 1)
+              .play(1, 3).play(2, 3)
+              .play(2, 1)
+          end
+
+          it "is in the GameOver state" do
+            engine.current_state.must_equal GameOver
+          end
+
+          describe "#continue_playing" do
+
+            before { engine.continue_playing }
+
+            it "is O's turn" do
+              engine.turn.must_equal Grid::O
+            end
+
+            it "has an empty grid" do
+              engine.grid.must_be :empty?
+            end
+
+            it "transitions to the Playing state" do
+              engine.current_state.must_equal Playing
+            end
+
+            it "triggers an event" do
+              last_event = engine_observer.last_event
+
+              last_event[:name].must_equal :game_started
+              last_event[:type].must_equal :continue_playing
+            end
+          end
+        end
+
+        describe "#stop" do
+
+          before do
+            engine
+              .start(Grid::X)
+              .play(1, 1).play(2, 1).play(1, 2).play(2, 2).play(1, 3)
+              .stop
+          end
+
+          it "resets the game" do
+            engine.turn.must_equal :nobody
+            engine.grid.must_be :empty?
+          end
+
+          it "transitions to the Init state" do
+            engine.current_state.must_equal Init
+          end
+
+          it "triggers an event" do
+            engine_observer.last_event[:name].must_equal :game_stopped
+          end
+        end
+
+        describe "what happens when calling illegal actions" do
+          before do
+            engine
+              .start(Grid::X)
+              .play(1, 1).play(2, 1).play(1, 2).play(2, 2).play(1, 3)
+          end
+
+          it "raises StateDesignPattern::IllegalStateException for the actions start and play" do
+            proc { engine.start(Grid::X) }.must_raise StateDesignPattern::IllegalStateException
+            proc { engine.play(1, 1) }.must_raise StateDesignPattern::IllegalStateException
+          end
+        end
+      end
+    end
+  end
+end