xo 0.0.1 → 1.0.0

data/lib/xo/engine.rb

@@ -1,137 +1,256 @@
-require 'observer'
-require 'ostruct'
-
 require 'xo/grid'
 require 'xo/evaluator'
 
 module XO
 
+  # A state machine that encapsulates the game logic for Tic-tac-toe. The operation
+  # of the engine is completely determined by the properties:
+  #
+  # - {#state},
+  # - {#turn},
+  # - {#grid}, and
+  # - {#last_event}.
+  #
+  # The engine can be in one of the 3 following states (represented by a symbol):
+  #
+  # - :init
+  # - :playing
+  # - :game_over
+  #
+  # The engine begins in the :init state. And, the following methods are used to advance
+  # a single game of Tic-tac-toe (and transition the engine between its states) by obeying
+  # the standard rules of Tic-tac-toe:
+  #
+  # - {#start}: [:init]
+  # - {#stop}: [:playing, :game_over]
+  # - {#play}: [:playing]
+  # - {#continue_playing}: [:game_over]
+  #
+  # The array of symbols after each method lists the states in which the method is allowed
+  # to be called.
+  #
+  # @example
+  #  e = Engine.new
+  #  e.start(Grid::X).play(1, 1).play(2, 1).play(1, 2).play(2, 2).play(1, 3)
+  #
+  #  event = e.last_event
+  #  puts event[:name]             # => :game_over
+  #  puts event[:type]             # => :winner
+  #  puts event[:last_move][:turn] # => Grid::X
+  #
+  #  e.continue_playing(Grid::O).play(2, 2).play(1, 1).play(3, 3).play(1, 3).play(1, 2).play(3, 2).play(2, 1).play(2, 3).play(3, 1)
+  #
+  #  event = e.last_event
+  #  puts event[:name]             # => :game_over
+  #  puts event[:type]             # => :squashed
+  #  puts event[:last_move][:turn] # => Grid::O
   class Engine
-    include Observable
 
-    attr_reader :turn, :state
+    # @return [:init, :playing, :game_over]
+    attr_reader :state
+
+    # @return [Grid::X, Grid::O, :nobody]
+    attr_reader :turn
+
+    # @return [Hash]
+    attr_reader :last_event
 
+    # Creates a new {Engine} with its state set to :init, turn set to :nobody, an empty grid and
+    # last_event set to { name: :new }.
     def initialize
       @grid = Grid.new
-      @turn = :nobody
-      @state = :idle
+
+      reset
+
+      set_event(:new)
     end
 
+    # Get the grid that's managed by the engine.
+    #
+    # @return [Grid] a copy of the grid that the engine uses
     def grid
       @grid.dup
     end
 
+    # If the current turn is either {Grid::X}, {Grid::O} or :nobody then
+    # it returns {Grid::O}, {Grid::X}, :nobody respectively.
+    #
+    # @return [Grid::X, Grid::O, :nobody]
     def next_turn
-      XO.other_player(turn)
+      Grid.other_token(turn)
     end
 
-    def start(player)
-      raise ArgumentError, "unknown player #{player}" unless XO.is_player?(player)
+    # Transitions the engine from the :init state into the :playing state.
+    #
+    # Sets the last event to be:
+    #
+    #   { name: :game_started }
+    #
+    # @param turn [Grid::X, Grid::O] the token to have first play
+    # @raise [ArgumentError] unless turn is either {Grid::X} or {Grid::O}
+    # @raise [IllegalStateError] unless it's called in the :init state
+    # @return [self]
+    def start(turn)
+      check_turn(turn)
 
       case state
-      when :idle
-        handle_start(player)
+      when :init
+        handle_start(turn)
       else
-        raise NotImplementedError
+        raise IllegalStateError, "must be in the :init state but state = :#{state}"
       end
-
-      self
     end
 
+    # Transitions the engine from the :playing or :game_over state into the :game_over state.
+    #
+    # Sets the last event to be:
+    #
+    #   { name: :game_over }
+    #
+    # @raise [IllegalStateError] unless it's called in the :playing or :game_over state
+    # @return [self]
     def stop
       case state
       when :playing, :game_over
         handle_stop
       else
-        raise NotImplementedError
+        raise IllegalStateError, "must be in the :playing or :game_over state but state = :#{state}"
       end
-
-      self
     end
 
+    # Makes a move at the given position (r, c) which may transition the engine into the :game_over state
+    # or leave it in the :playing state.
+    #
+    # Sets the last event as follows:
+    #
+    # - If the position is out of bounds, then
+    #
+    #     { name: :invalid_move, type: :out_of_bounds }
+    #
+    # - If the position is occupied, then
+    #
+    #     { name: :invalid_move, type: :occupied }
+    #
+    # - If the move was allowed and didn't result in ending the game, then
+    #
+    #     { name: :next_turn, last_move: { turn: :a_token, r: :a_row, c: :a_column } }
+    #
+    # - If the move was allowed and resulted in a win, then
+    #
+    #     { name: :game_over, type: :winner, last_move: { turn: :a_token, r: :a_row, c: :a_column }, details: :the_details }
+    #
+    # - If the move was allowed and resulted in a squashed game, then
+    #
+    #     { name: :game_over, type: :squashed, last_move: { turn: :a_token, r: :a_row, c: :a_column } }
+    #
+    # Legend:
+    #
+    # - :a_token is one of {Grid::X} or {Grid::O}
+    # - :a_row is one of 1, 2 or 3
+    # - :a_column is one of 1, 2 or 3
+    # - :the_details is taken verbatim from the :details key of the returned hash of {Evaluator.analyze}
+    #
+    # @param r [Integer] the row
+    # @param c [Integer] the column
+    # @raise [IllegalStateError] unless it's called in the :playing state
+    # @return [self]
     def play(r, c)
       case state
       when :playing
-        handle_play(r.to_i, c.to_i)
+        handle_play(r, c)
       else
-        raise NotImplementedError
+        raise IllegalStateError, "must be in the :playing state but state = :#{state}"
       end
-
-      self
     end
 
-    def continue_playing(player)
-      raise ArgumentError, "unknown player #{player}" unless XO.is_player?(player)
+    # Similar to start but should only be used to play another round when a game has ended. It transitions
+    # the engine from the :game_over state into the :playing state.
+    #
+    # Sets the last event to be:
+    #
+    #   { name: :game_started, type: :continue_playing }
+    #
+    # @param turn [Grid::X, Grid::O] the token to have first play
+    # @raise [ArgumentError] unless turn is either {Grid::X} or {Grid::O}
+    # @raise [IllegalStateError] unless it's called in the :game_over state
+    # @return [self]
+    def continue_playing(turn)
+      check_turn(turn)
 
       case state
       when :game_over
-        handle_continue_playing(player)
+        handle_continue_playing(turn)
       else
-        raise NotImplementedError
+        raise IllegalStateError, "must be in the :game_over state but state = :#{state}"
       end
-
-      self
     end
 
-    private
+    # The exception raised by {#start}, {#stop}, {#play} and {#continue_playing} whenever
+    # these methods are called and the engine is in the wrong state.
+    class IllegalStateError < StandardError; end
 
-      attr_writer :turn, :state
+    private
 
-      def handle_start(player)
-        self.turn = player
-        self.state = :playing
+      def handle_start(turn)
+        @state = :playing
+        @turn = turn
         @grid.clear
 
-        send_event(:game_started, who: player)
+        set_event(:game_started)
       end
 
       def handle_stop
-        self.state = :idle
+        reset
 
-        send_event(:game_stopped)
+        set_event(:game_stopped)
       end
 
       def handle_play(r, c)
-        if Grid.contains?(r, c)
-          if @grid.free?(r, c)
-            @grid[r, c] = turn
-            last_played_at = OpenStruct.new(row: r, col: c)
-
-            result = Evaluator.analyze(@grid, turn)
-
-            case result[:status]
-            when :ok
-              self.turn = next_turn
-              send_event(:next_turn, who: turn, last_played_at: last_played_at)
-            when :game_over
-              self.state = :game_over
-
-              case result[:type]
-              when :winner
-                send_event(:game_over, type: :winner, who: turn, last_played_at: last_played_at, details: result[:details])
-              when :squashed
-                send_event(:game_over, type: :squashed, who: turn, last_played_at: last_played_at)
-              end
-            end
-          else
-            send_event(:invalid_move, type: :occupied)
+        return set_event(:invalid_move, type: :out_of_bounds) unless Grid.contains?(r, c)
+        return set_event(:invalid_move, type: :occupied) unless @grid.open?(r, c)
+
+        @grid[r, c] = turn
+        last_move = { turn: turn, r: r, c: c }
+
+        result = Evaluator.instance.analyze(@grid, turn)
+
+        case result[:status]
+        when :ok
+          @turn = next_turn
+          set_event(:next_turn, last_move: last_move)
+        when :game_over
+          @state = :game_over
+
+          case result[:type]
+          when :winner
+            set_event(:game_over, type: :winner, last_move: last_move, details: result[:details])
+          when :squashed
+            set_event(:game_over, type: :squashed, last_move: last_move)
           end
-        else
-          send_event(:invalid_move, type: :out_of_bounds)
         end
       end
 
-      def handle_continue_playing(player)
-        self.turn = player
-        self.state = :playing
+      def handle_continue_playing(turn)
+        @turn = turn
+        @state = :playing
         @grid.clear
 
-        send_event(:continue_playing, who: player)
+        set_event(:game_started, type: :continue_playing)
+      end
+
+      def check_turn(turn)
+        raise ArgumentError, "illegal token #{turn}" unless Grid.is_token?(turn)
+      end
+
+      def reset
+        @state = :init
+        @turn = :nobody
+        @grid.clear
       end
 
-      def send_event(name, message = {})
-        changed
-        notify_observers({ event: name }.merge(message))
+      def set_event(name, message = {})
+        @last_event = { name: name }.merge(message)
+        self
       end
   end
 end

data/lib/xo/evaluator.rb

@@ -1,31 +1,125 @@
-module XO
+require 'singleton'
 
-  module Evaluator
+require 'xo/grid'
 
-    def self.analyze(grid, player)
-      @grid = grid
-      @player = player
+module XO
 
+  # This class defines an {Evaluator#analyze} method than can be used to look at a grid and
+  # 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.
+  # 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.
+    #
+    # It can return a hash in following formats:
+    #
+    # - If everything is fine, then
+    #
+    #     { status: :ok }
+    #
+    # - 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 }] }
+    #
+    # - 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 }] }
+    #
+    # - If the game is over due to a squashed grid, then
+    #
+    #     { status: :game_over, type: :squashed }
+    #
+    # - If there is too much of one token, then
+    #
+    #     { status: :invalid_grid, type: :too_many_moves_ahead }
+    #
+    # - If both tokens are arranged in winning positions, then
+    #
+    #     { status: :invalid_grid, type: :two_winners }
+    #
+    # 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
+    #
+    # 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
+    #   ---+---+---
+    #    o | x | o
+    #   ---+---+---
+    #    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 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)
       perform_analysis
     end
 
+    # Returns the number of {Grid::X}'s and {Grid::O}'s in the given grid.
+    #
+    # @example
+    #  g = Grid.new('xoxxo')
+    #  xs, os = Evaluator.instance.xos(g)
+    #  puts xs # => 3
+    #  puts os # => 2
+    #
+    # @return [Array(Integer, Integer)]
+    def xos(grid)
+      xs = os = 0
+
+      grid.each do |_, _, val|
+        xs += 1 if val == Grid::X
+        os += 1 if val == Grid::O
+      end
+
+      [xs, os]
+    end
+
     private
 
-      class << self
-        attr_reader :grid, :player, :winners
+      attr_reader :grid, :token, :winners
+
+      def check_token(token)
+        raise ArgumentError, "illegal token #{token}" unless Grid.is_token?(token)
       end
 
-      def self.perform_analysis
-        return { status: :error, type: :too_many_moves_ahead } if two_or_more_moves_ahead?
+      def init_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?
 
         find_winners
 
         if two_winners?
-          { status: :error, type: :two_winners }
-        elsif winners[player]
-          { status: :game_over, type: :winner, details: winners[player] }
-        elsif winners[other_player]
-          { status: :game_over, type: :loser, details: winners[other_player] }
+          { 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 }
@@ -35,74 +129,55 @@ module XO
         end
       end
 
-      def self.two_or_more_moves_ahead?
+      def two_or_more_moves_ahead?
         moves_ahead >= 2
       end
 
-      def self.moves_ahead
-        xs = os = 0
-
-        grid.each do |_, _, val|
-          xs += 1 if val == XO::X
-          os += 1 if val == XO::O
-        end
+      def moves_ahead
+        xs, os = xos(grid)
 
         (xs - os).abs
       end
 
-      def self.find_winners
-        @winners = {}
+      def find_winners
+        winning_positions.each do |w|
+          a = grid[*w[:positions][0]]
+          b = grid[*w[:positions][1]]
+          c = grid[*w[:positions][2]]
 
-        # check rows
-        if XO.is_token?(grid[1, 1]) && grid[1, 1] == grid[1, 2] && grid[1, 2] == grid[1, 3]
-          add_winner(grid[1, 1], { where: :row, index: 1, positions: [[1, 1], [1, 2], [1, 3]] })
-        end
-
-        if XO.is_token?(grid[2, 1]) && grid[2, 1] == grid[2, 2] && grid[2, 2] == grid[2, 3]
-          add_winner(grid[2, 1], { where: :row, index: 2, positions: [[2, 1], [2, 2], [2, 3]] })
-        end
-
-        if XO.is_token?(grid[3, 1]) && grid[3, 1] == grid[3, 2] && grid[3, 2] == grid[3, 3]
-          add_winner(grid[3, 1], { where: :row, index: 3, positions: [[3, 1], [3, 2], [3, 3]] })
-        end
-
-        # check columns
-        if XO.is_token?(grid[1, 1]) && grid[1, 1] == grid[2, 1] && grid[2, 1] == grid[3, 1]
-          add_winner(grid[1, 1], { where: :column, index: 1, positions: [[1, 1], [2, 1], [3, 1]] })
-        end
-
-        if XO.is_token?(grid[1, 2]) && grid[1, 2] == grid[2, 2] && grid[2, 2] == grid[3, 2]
-          add_winner(grid[1, 2], { where: :column, index: 2, positions: [[1, 2], [2, 2], [3, 2]] })
+          add_winner(a, w) if Grid.is_token?(a) && a == b && b == c
         end
+      end
 
-        if XO.is_token?(grid[1, 3]) && grid[1, 3] == grid[2, 3] && grid[2, 3] == grid[3, 3]
-          add_winner(grid[1, 3], { where: :column, index: 3, positions: [[1, 3], [2, 3], [3, 3]] })
-        end
+      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]] },
 
-        # check diagonals
-        if XO.is_token?(grid[1, 1]) && grid[1, 1] == grid[2, 2] && grid[2, 2] == grid[3, 3]
-          add_winner(grid[1, 1], { where: :diagonal, index: 1, positions: [[1, 1], [2, 2], [3, 3]] })
-        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]] },
 
-        if XO.is_token?(grid[1, 3]) && grid[1, 3] == grid[2, 2] && grid[2, 2] == grid[3, 1]
-          add_winner(grid[1, 3], { where: :diagonal, index: 2, positions: [[1, 3], [2, 2], [3, 1]] })
-        end
+          { where: :diagonal, index: 1, positions: [[1, 1], [2, 2], [3, 3]] },
+          { where: :diagonal, index: 2, positions: [[1, 3], [2, 2], [3, 1]] }
+        ]
       end
 
-      def self.add_winner(player, details)
-        if winners.key?(player)
-          winners[player] << details
+      def add_winner(token, details)
+        if winners.key?(token)
+          winners[token] << details
         else
-          winners[player] = [details]
+          winners[token] = [details]
         end
       end
 
-      def self.two_winners?
-        winners[XO::X] && winners[XO::O]
+      def two_winners?
+        winners[Grid::X] && winners[Grid::O]
       end
 
-      def self.other_player
-        XO.other_player(player)
+      def other_token
+        Grid.other_token(token)
       end
   end
 end