xo 1.0.0 → 1.1.0

data/lib/xo/ai/player.rb

@@ -0,0 +1,44 @@
+module XO
+
+  module AI
+
+    class Player
+
+      attr_reader :token
+
+      def initialize(token)
+        @token = token
+      end
+
+      def terminal_score(outcome)
+        send("#{outcome}_value")
+      end
+
+      def non_terminal_score(next_grids, scores)
+        best_score(compute_next_grids_scores(next_grids, scores))
+      end
+
+      def best_score(next_grids_scores)
+        raise NotImplementedError
+      end
+
+      def winner_value
+        raise NotImplementedError
+      end
+
+      def loser_value
+        raise NotImplementedError
+      end
+
+      def squashed_value
+        0
+      end
+
+      private
+
+        def compute_next_grids_scores(next_grids, scores)
+          next_grids.map { |grid| scores[grid] }
+        end
+    end
+  end
+end

data/lib/xo/engine.rb

@@ -1,256 +1,54 @@
+require 'state_design_pattern'
+
 require 'xo/grid'
 require 'xo/evaluator'
+require 'xo/engine/game_context'
+require 'xo/engine/init'
 
 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} encapsulates the game logic for Tic-tac-toe.
   #
-  # The engine can be in one of the 3 following states (represented by a symbol):
+  # It is controlled by 4 actions:
   #
-  # - :init
-  # - :playing
-  # - :game_over
+  # - start
+  # - stop
+  # - play
+  # - continue_playing
   #
-  # 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:
+  # Each action may or may not change the state of the engine. This is important
+  # because it is the state of the engine that determines when the above actions
+  # can be called.
   #
-  # - {#start}: [:init]
-  # - {#stop}: [:playing, :game_over]
-  # - {#play}: [:playing]
-  # - {#continue_playing}: [:game_over]
+  # The engine can be in 1 of 3 states:
   #
-  # The array of symbols after each method lists the states in which the method is allowed
-  # to be called.
+  # - {Init}
+  # - {Playing}
+  # - {GameOver}
   #
-  # @example
-  #  e = Engine.new
-  #  e.start(Grid::X).play(1, 1).play(2, 1).play(1, 2).play(2, 2).play(1, 3)
+  # The engine begins life in the {Init} state.
   #
-  #  event = e.last_event
-  #  puts event[:name]             # => :game_over
-  #  puts event[:type]             # => :winner
-  #  puts event[:last_move][:turn] # => Grid::X
+  # Here's a table showing which actions can be called in a given state:
   #
-  #  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)
+  #   State    | Actions
+  #   ----------------------------------
+  #   Init     | start
+  #   Playing  | play, stop
+  #   GameOver | continue_playing, stop
   #
-  #  event = e.last_event
-  #  puts event[:name]             # => :game_over
-  #  puts event[:type]             # => :squashed
-  #  puts event[:last_move][:turn] # => Grid::O
-  class Engine
-
-    # @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
-
-      reset
-
-      set_event(:new)
-    end
+  # Each action is defined in their respective state class.
+  class Engine < StateDesignPattern::StateMachine
 
-    # Get the grid that's managed by the engine.
-    #
-    # @return [Grid] a copy of the grid that the engine uses
-    def grid
-      @grid.dup
+    def start_state
+      Init
     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
-      Grid.other_token(turn)
+    def initial_context
+      GameContext.new(:nobody, Grid.new)
     end
 
-    # 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 :init
-        handle_start(turn)
-      else
-        raise IllegalStateError, "must be in the :init state but state = :#{state}"
-      end
-    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 IllegalStateError, "must be in the :playing or :game_over state but state = :#{state}"
-      end
-    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, c)
-      else
-        raise IllegalStateError, "must be in the :playing state but state = :#{state}"
-      end
-    end
-
-    # 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(turn)
-      else
-        raise IllegalStateError, "must be in the :game_over state but state = :#{state}"
-      end
+    def evaluator
+      Evaluator.instance
     end
-
-    # 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
-
-    private
-
-      def handle_start(turn)
-        @state = :playing
-        @turn = turn
-        @grid.clear
-
-        set_event(:game_started)
-      end
-
-      def handle_stop
-        reset
-
-        set_event(:game_stopped)
-      end
-
-      def handle_play(r, c)
-        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
-        end
-      end
-
-      def handle_continue_playing(turn)
-        @turn = turn
-        @state = :playing
-        @grid.clear
-
-        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 set_event(name, message = {})
-        @last_event = { name: name }.merge(message)
-        self
-      end
   end
 end

data/lib/xo/engine/game_context.rb

@@ -0,0 +1,28 @@
+require 'xo/grid'
+
+module XO
+
+  class GameContext < Struct.new(:turn, :grid)
+
+    def reset
+      set_turn_and_clear_grid(:nobody)
+    end
+
+    def set_turn_and_clear_grid(turn)
+      self.turn = turn
+      grid.clear
+    end
+
+    def switch_turns
+      self.turn = next_turn
+    end
+
+    def next_turn
+      Grid.other_token(turn)
+    end
+
+    def check_turn(turn)
+      raise ArgumentError, "invalid turn symbol, #{turn}" unless Grid.is_token?(turn)
+    end
+  end
+end

data/lib/xo/engine/game_over.rb

@@ -0,0 +1,33 @@
+require 'xo/engine/game_state'
+
+module XO
+
+  class GameOver < GameState
+
+    # Stops and resets a game.
+    #
+    # The engine is transitioned into the {Init} state and the event
+    #
+    #   { name: :game_stopped }
+    #
+    # is triggered.
+    def stop
+      stop_game
+    end
+
+    # Starts another new game.
+    #
+    # The token that won plays first, otherwise the game was squashed and so
+    # the next token plays first.
+    #
+    # The engine is transitioned into the {Playing} state and the event
+    #
+    #   { name: :game_started, type: :continue_playing }
+    #
+    # is triggered.
+    def continue_playing
+      game_context.set_turn_and_clear_grid(game_context.turn)
+      engine.transition_to_state_and_send_event(Playing, :game_started, type: :continue_playing)
+    end
+  end
+end

data/lib/xo/engine/game_state.rb

@@ -0,0 +1,21 @@
+require 'state_design_pattern'
+
+module XO
+
+  class GameState < StateDesignPattern::BaseState
+    def_actions :start, :stop, :play, :continue_playing
+
+    private
+
+      alias_method :engine, :state_machine
+
+      def game_context
+        engine.context
+      end
+
+      def stop_game
+        game_context.reset
+        engine.transition_to_state_and_send_event(Init, :game_stopped)
+      end
+  end
+end

data/lib/xo/engine/init.rb

@@ -0,0 +1,24 @@
+require 'xo/engine/game_state'
+require 'xo/engine/playing'
+
+module XO
+
+  class Init < GameState
+
+    # Starts a new game.
+    #
+    # The engine is transitioned into the {Playing} state and the event
+    #
+    #   { name: :game_started }
+    #
+    # is triggered.
+    #
+    # @param turn [Grid::X, Grid::O] specifies which token has first play
+    # @raise [ArgumentError] unless turn is either {Grid::X} or {Grid::O}
+    def start(turn)
+      game_context.check_turn(turn)
+      game_context.set_turn_and_clear_grid(turn)
+      engine.transition_to_state_and_send_event(Playing, :game_started)
+    end
+  end
+end

data/lib/xo/engine/playing.rb

@@ -0,0 +1,88 @@
+require 'xo/engine/game_state'
+require 'xo/engine/game_over'
+
+module XO
+
+  class Playing < GameState
+
+    # Stops and resets a game.
+    #
+    # The engine is transitioned into the {Init} state and the event
+    #
+    #   { name: :game_stopped }
+    #
+    # is triggered.
+    def stop
+      stop_game
+    end
+
+    # Attempts to make a move at the given position (r, c).
+    #
+    # The following outcomes are possible:
+    #
+    # - If the position is *out* *of* *bounds*, then the event below is
+    #   triggered and the engine remains in this state.
+    #
+    #     { name: :invalid_move, type: :out_of_bounds }
+    #
+    # - If the position is *occupied*, then the event below is triggered and the
+    #   engine remains in this state.
+    #
+    #     { name: :invalid_move, type: :occupied }
+    #
+    # - If the move results in a *win*, then the event below is triggered and
+    #   the engine is transitioned into the {GameOver} state.
+    #
+    #     { name: :game_over, type: :winner, last_move: { turn: :token, r: :row, c: :column }, details: :details }
+    #
+    # - If the move results in a *squashed* game, then the event below is
+    #   triggered and the engine is transitioned into the {GameOver} state.
+    #
+    #     { name: :game_over, type: :squashed, last_move: { turn: :next_token, r: :row, c: :column } }
+    #
+    # - Otherwise, the event below is triggered and the engine remains in this
+    #   state.
+    #
+    #     { name: :next_turn, last_move: { turn: :token, r: :row, c: :column } }
+    #
+    # *Legend:*
+    #
+    # - *:token* is one of {Grid::X} or {Grid::O}
+    # - *:next_token* is one of {Grid::X} or {Grid::O}
+    # - *:row* is one of 1, 2 or 3
+    # - *:column* is one of 1, 2 or 3
+    # - *: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
+    def play(r, c)
+      return engine.send_event(:invalid_move, type: :out_of_bounds) unless Grid.contains?(r, c)
+      return engine.send_event(:invalid_move, type: :occupied) unless game_context.grid.open?(r, c)
+
+      game_context.grid[r, c] = game_context.turn
+      last_move = { turn: game_context.turn, r: r, c: c }
+
+      result = engine.evaluator.analyze(game_context.grid, game_context.turn)
+
+      case result[:status]
+      when :ok
+        game_context.switch_turns
+        engine.send_event(:next_turn, last_move: last_move)
+      when :game_over
+        case result[:type]
+        when :winner
+          engine.transition_to_state_and_send_event(
+            GameOver,
+            :game_over, type: :winner, last_move: last_move, details: result[:details]
+          )
+        when :squashed
+          game_context.switch_turns
+          engine.transition_to_state_and_send_event(
+            GameOver,
+            :game_over, type: :squashed, last_move: last_move
+          )
+        end
+      end
+    end
+  end
+end