xo 0.0.1 → 1.0.0

data/lib/xo/grid.rb

@@ -1,30 +1,114 @@
 module XO
 
+  # A data structure for storing {X}'s and {O}'s in a 3x3 grid.
+  #
+  # The grid is structured as follows:
+  #
+  #        column
+  #       1   2   3
+  #   row
+  #    1    |   |
+  #      ---+---+---
+  #    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
+
     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
 
-    def initialize
-      @grid = Array.new(ROWS * COLS, :e)
+    # 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
+    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)
     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) }
+    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) }
+    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)
       if self.class.contains?(r, c)
-        grid[idx(r, c)] = val
+        grid[idx(r, c)] = self.class.is_token?(val) ? val : :e
       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)]
@@ -33,49 +117,90 @@ module XO
       end
     end
 
-    def empty?
-      grid.all? { |val| !XO.is_token?(val) }
-    end
-
-    def full?
-      grid.all? { |val| XO.is_token?(val) }
-    end
-
-    def free?(r, c)
-      !XO.is_token?(self[r, c])
+    # 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
     end
 
+    # Used for iterating over all the positions of the grid from left to right and top to bottom.
+    #
+    # @example
+    #  g = Grid.new
+    #  g.each do |r, c, val|
+    #    puts "(#{r}, #{c}) -> #{val}"
+    #  end
     def each
       (1..ROWS).each do |r|
         (1..COLS).each do |c|
           yield(r, c, self[r, c])
         end
       end
-
-      self
     end
 
-    def each_free
-      self.each { |r, c, _| yield(r, c) if free?(r, c) }
+    # Used for iterating over all the open positions of the grid from left to right and top to bottom.
+    #
+    # @example
+    #  g = Grid.new
+    #
+    #  g[1, 1] = g[2, 1] = Grid::X
+    #  g[2, 2] = g[3, 1] = Grid::O
+    #
+    #  g.each_open do |r, c|
+    #    puts "(#{r}, #{c}) is open"
+    #  end
+    def each_open
+      self.each { |r, c, _| yield(r, c) if open?(r, c) }
     end
 
-    def ==(other)
-      return false unless other.instance_of?(self.class)
-      grid == other.instance_variable_get(:@grid)
+    # Returns a string representation of the grid which may be useful
+    # for debugging.
+    def inspect
+      grid.map { |val| t(val) }.join
     end
-    alias_method :eql?, :==
 
-    def hash
-      grid.hash
+    # Returns a string representation of the grid which may be useful
+    # for display.
+    def to_s
+      g = grid.map { |val| t(val) }
+
+      [" #{g[0]} | #{g[1]} | #{g[2]} ",
+       "---+---+---",
+       " #{g[3]} | #{g[4]} | #{g[5]} ",
+       "---+---+---",
+       " #{g[6]} | #{g[7]} | #{g[8]} "].join("\n")
     end
 
     private
 
-      attr_reader :grid
+      def from_string(g)
+        g = g.to_s
+        l = g.length
+
+        g = if l < N
+          g + ' ' * (N - l)
+        elsif l > N
+          g[0..N-1]
+        else
+          g
+        end
+
+        g.split('').map do |ch|
+          sym = ch.to_sym
+          sym == X || sym == O ? sym : :e
+        end
+      end
 
       # Computes the 0-based index of position (r, c) on a 3x3 grid.
       #
@@ -91,5 +216,9 @@ module XO
       def idx(r, c)
         COLS * (r - 1) + (c - 1)
       end
+
+      def t(val)
+        self.class.is_token?(val) ? val : ' '
+      end
   end
 end

data/lib/xo/version.rb

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

data/spec/spec_helper.rb

@@ -1,3 +1,6 @@
+require 'coveralls'
+Coveralls.wear!
+
 require 'minitest/autorun'
 require 'minitest/spec'
 

data/spec/xo/ai/geometric_grid_spec.rb

@@ -0,0 +1,137 @@
+require 'spec_helper'
+
+module XO::AI
+
+  describe GeometricGrid do
+
+    let(:grid) { GeometricGrid.new }
+
+    describe "#rotate" do
+
+      let (:grid) { GeometricGrid.new("xoooxxoxo") }
+
+      it "correctly performs a single rotation" do
+        rotated_grid = grid.rotate
+
+        rotated_grid.inspect.must_equal "ooxxxooxo"
+      end
+
+      it "returns the original on the 4th rotation" do
+        original_grid = grid.rotate.rotate.rotate.rotate
+
+        original_grid.same?(grid).must_equal true
+      end
+    end
+
+    describe "#reflect" do
+
+      let (:grid) { GeometricGrid.new("oxxxoooxo") }
+
+      it "correctly performs a single reflection" do
+        reflected_grid = grid.reflect
+
+        reflected_grid.inspect.must_equal "xxoooxoxo"
+      end
+
+      it "returns the original on the 2nd reflection" do
+        original_grid = grid.reflect.reflect
+
+        original_grid.same?(grid).must_equal true
+      end
+    end
+
+    describe "#same?" do
+
+      it "returns true iff two grids have the same occupied positions" do
+        a = GeometricGrid.new('x')
+        b = GeometricGrid.new('  x')
+
+        a.same?(a).must_equal true
+        a.same?(b).must_equal false # but they are equivalent
+      end
+    end
+
+    describe "#equivalent?" do
+
+      it "correctly determines equivalent grids" do
+        a = GeometricGrid.new('x')
+
+        ['  x', '        x', '      x'].each do |g|
+          a.equivalent?(GeometricGrid.new(g)).must_equal true
+        end
+
+        b = GeometricGrid.new(' x')
+
+        ['     x', '       x', '   x'].each do |g|
+          b.equivalent?(GeometricGrid.new(g)).must_equal true
+        end
+
+        c = GeometricGrid.new('xo')
+
+        [' ox', '     o  x', '      xo', 'x  o'].each do |g|
+          c.equivalent?(GeometricGrid.new(g)).must_equal true
+        end
+      end
+
+      it "can only determine the equivalence of two geometric grids" do
+        a = GeometricGrid.new('x')
+        b = XO::Grid.new('  x')
+
+        a.equivalent?(b).must_equal false
+      end
+    end
+
+    describe "equality" do
+
+      it "is reflexive, symmetric and transitive" do
+        a = GeometricGrid.new('x')
+        b = GeometricGrid.new('  x')
+        c = GeometricGrid.new('        x')
+
+        # reflexive, not quite since we didn't test for all a
+        a.must_equal a
+
+        # symmetric
+        a.must_equal b
+        b.must_equal a
+
+        # transitive
+        b.must_equal c
+        a.must_equal c
+      end
+
+      describe "#== and #eql?" do
+
+        it "must be the case that if two geometric grid are #== then they are also #eql?" do
+          a = GeometricGrid.new('x')
+          b = GeometricGrid.new('  x')
+
+          a.eql?(b).must_equal true
+        end
+      end
+    end
+
+    describe "#hash" do
+
+      it "must return the same hash for equal geometric grids" do
+        a = GeometricGrid.new('     x')
+        b = GeometricGrid.new('       x')
+
+        a.hash.must_equal b.hash
+      end
+    end
+
+    describe "when used within a hash" do
+
+      it "must be the case that equivalent grids map to the same key" do
+        a = GeometricGrid.new('x')
+        b = GeometricGrid.new('  x')
+
+        hash = {}
+        hash[a] = :any_value
+
+        hash[b].must_equal :any_value
+      end
+    end
+  end
+end

data/spec/xo/ai/minimax_spec.rb

@@ -1,63 +1,83 @@
 require 'spec_helper'
 
-module XO
+module XO::AI
 
-  describe AI do
+  describe Minimax do
 
-    describe 'minimax' do
+    let(:minimax) { Minimax.instance }
 
-      let(:grid) { Grid.new }
+    describe "immediate wins" do
 
-      describe 'immediate wins' do
+      it "should return (1, 3)" do
+        grid = XO::Grid.new('xx oo')
 
-        it 'should return (1, 3)' do
-          grid[1, 1] = grid[1, 2] = :x
-          grid[2, 1] = grid[2, 2] = :o
+        moves = minimax.moves(grid, XO::Grid::X)
 
-          moves = AI.minimax(grid, :x).moves
+        moves.must_equal [[1, 3]]
+      end
 
-          moves.size.must_equal 1
-          [moves[0].row, moves[0].column].must_equal [1, 3]
-        end
+      it "should return (1, 3), (3, 2) and (3, 3)" do
+        grid = XO::Grid.new('oo xoxx')
+
+        moves = minimax.moves(grid, XO::Grid::O)
 
-        it 'should return (1, 3), (3, 2) and (3, 3)' do
-          grid[2, 1] = grid[2, 3] = grid[3, 1] = :x
-          grid[1, 1] = grid[1, 2] = grid[2, 2] = :o
+        moves.must_equal [[1, 3], [3, 2], [3, 3]]
+      end
+    end
 
-          moves = AI.minimax(grid, :o).moves
+    describe "blocking moves" do
 
-          moves.size.must_equal 3
-          [moves[0].row, moves[0].column].must_equal [1, 3]
-          [moves[1].row, moves[1].column].must_equal [3, 2]
-          [moves[2].row, moves[2].column].must_equal [3, 3]
-        end
+      it "should return (2, 1)" do
+        grid = XO::Grid.new('x   o x')
+
+        moves = minimax.moves(grid, XO::Grid::O)
+
+        moves.must_equal [[2, 1]]
       end
+    end
 
-      describe 'blocking moves' do
+    describe "smart moves" do
 
-        it 'should return (2, 1)' do
-          grid[1, 1] = grid[3, 1] = :x
-          grid[2, 2] = :o
+      it "should return (1, 3)" do
+        grid = XO::Grid.new('x  o  x o')
 
-          moves = AI.minimax(grid, :o).moves
+        moves = minimax.moves(grid, XO::Grid::X)
 
-          moves.size.must_equal 1
-          [moves[0].row, moves[0].column].must_equal [2, 1]
-        end
+        moves.must_equal [[1, 3]]
       end
 
-      describe 'smart moves' do
+      it "should return (1, 2), (2, 1), (2, 3), (3, 2)" do
+        grid = XO::Grid.new('  o x o')
 
-        it 'should return (1, 3)' do
-          grid[1, 1] = grid[3, 1] = :x
-          grid[2, 1] = grid[3, 3] = :o
+        moves = minimax.moves(grid, XO::Grid::X)
 
-          moves = AI.minimax(grid, :x).moves
+        moves.must_equal [[1, 2], [2, 1], [2, 3], [3, 2]]
+      end
 
-          moves.size.must_equal 1
-          [moves[0].row, moves[0].column].must_equal [1, 3]
+      it "should return (1, 3), (3, 1)" do
+        grid = XO::Grid.new('x   x   o')
+
+        moves = minimax.moves(grid, XO::Grid::O)
+
+        moves.must_equal [[1, 3], [3, 1]]
+      end
+    end
+
+    describe "moves" do
+
+      it "raises ArgumentError if turn is not a token" do
+        proc { minimax.moves(XO::Grid.new, :not_a_token) }.must_raise ArgumentError
+      end
+
+      it "raises ArgumentError for an invalid grid and/or turn combination" do
+        [['x', XO::Grid::X], ['xoo', XO::Grid::O], ['oo', XO::Grid::O], ['xx', XO::Grid::X]].each do |input|
+          proc { minimax.moves(XO::Grid.new(input[0]), input[1]) }.must_raise ArgumentError
         end
       end
+
+      it "returns [] for a terminal grid" do
+        minimax.moves(XO::Grid.new('xx ooo'), XO::Grid::X).must_equal []
+      end
     end
   end
 end