xo 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f4e9916b4a489801329e2b8713a883a06ebef55f
+  data.tar.gz: 83ea35a8950526c5ab4a10587ac151ce3523f6d6
+SHA512:
+  metadata.gz: ff7f19ed461e17028efaeda45010b6faf967103640d004b80da343f179dd4dbf307577aeebfb38bcfeda61f33c01b45657ea5ceadd911c7ca134496d6ff532b5
+  data.tar.gz: e31c7c082b239cd9e3efc10edb36e9e92197e383b4da15f84f8a9d6520fa55c72ccbaa743d3e0aa1fe224f4260bf2c8e4327b57d564eaa1aea8148dd310aa06b

data/.gitignore

@@ -0,0 +1 @@
+*.gem

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Dwayne R. Crooks
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,55 @@
+# xo
+
+A [Ruby](http://www.ruby-lang.org/en/) library for [Tic-tac-toe](http://en.wikipedia.org/wiki/Tic-tac-toe).
+
+# Performance of the Minimax Algorithm
+
+```ruby
+require 'benchmark'
+require 'xo'
+
+# Empty grid
+g = XO::Grid.new
+
+puts Benchmark.measure { XO::AI.minimax(g, :x) }
+# => 0.000000   0.000000   0.000000 (  0.000463)
+# => O(1) time due to caching
+
+# One spot taken
+g[1, 1] = :x
+
+puts Benchmark.measure { XO::AI.minimax(g, :o) }
+# => 0.000000   0.000000   0.000000 (  0.000216)
+# => O(1) time due to caching
+
+# Two spots taken
+g[1, 3] = :o
+
+puts Benchmark.measure { XO::AI.minimax(g, :x) }
+# => 0.690000   0.000000   0.690000 (  0.695095)
+# => Worst-case time, performance only improves from here on as the grid gets filled
+```
+
+# Testing
+
+You can run:
+
+- All tests: `rake test`
+- One test: `ruby -Ilib -Ispec spec/path_to_spec_file.rb`
+
+# TODO
+
+1. Write documentation.
+2. Show example usage.
+3. Write an example Tic-tac-toe command-line game client.
+
+# 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:
+
+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).
+
+# 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.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+  t.libs.push 'spec'
+end

data/lib/xo.rb

@@ -0,0 +1,25 @@
+module XO
+
+  X = :x
+  O = :o
+
+  def self.is_token?(val)
+    [X, O].include?(val)
+  end
+
+  def self.other_token(token)
+    token == X ? O : (token == O ? X : token)
+  end
+
+  class << self
+    alias_method :is_player?, :is_token?
+    alias_method :other_player, :other_token
+  end
+
+  class Position < Struct.new(:row, :column); end
+end
+
+require 'xo/grid'
+require 'xo/evaluator'
+require 'xo/engine'
+require 'xo/ai'

data/lib/xo/ai.rb

@@ -0,0 +1,4 @@
+require 'xo/ai/minimax'
+require 'xo/ai/expert'
+require 'xo/ai/novice'
+require 'xo/ai/advanced_beginner'

data/lib/xo/ai/advanced_beginner.rb

@@ -0,0 +1,17 @@
+require 'xo/ai/expert'
+
+module XO::AI
+
+  class AdvancedBeginner < Expert
+
+    def self.get_moves(grid, player)
+      smart_moves = super(grid, player)
+      dumb_moves  = all_moves - smart_moves
+
+      # if there are no dumb moves then we have no choice but to make a smart move
+      # otherwise, 75% of the time we'll make a smart move and the other 25% of the
+      # time we'll make a dumb move
+      dumb_moves.empty? ? smart_moves : (rand < 0.75 ? smart_moves : dumb_moves)
+    end
+  end
+end

data/lib/xo/ai/expert.rb

@@ -0,0 +1,64 @@
+require 'xo/grid'
+require 'xo/evaluator'
+require 'xo/ai'
+
+module XO::AI
+
+  class Expert
+
+    def self.suggest_moves(grid, player)
+      result = XO::Evaluator.analyze(grid, player)
+
+      case result[:status]
+      when :ok
+        get_moves(grid, player)
+      when :game_over
+        []
+      else
+        raise IllegalGridStatusError
+      end
+    end
+
+    def self.get_moves(grid, player)
+      if moves = MOVES_CACHE[grid] || MOVES_CACHE[invert_grid(grid)]
+        moves.map { |pos| XO::Position.new(*pos) }
+      else
+        XO::AI.minimax(grid, player).moves
+      end
+    end
+
+    def self.all_moves(grid)
+      grid.enum_for(:each_free).map { |r, c| XO::Position.new(r, c) }
+    end
+
+    private
+
+      def self.invert_grid(grid)
+        (new_grid = grid.dup).each do |r, c, val|
+          new_grid[r, c] = XO::other_token(val)
+        end
+      end
+
+      def self.one_x_grid(r, c)
+        XO::Grid.new.tap do |grid|
+          grid[r, c] = :x
+        end
+      end
+
+      MOVES_CACHE = {
+        XO::Grid.new => [[1, 1], [1, 2], [1, 3], [2, 1], [2, 2], [2, 3], [3, 1], [3, 2], [3, 3]],
+
+        one_x_grid(1, 1) => [[2, 2]],
+        one_x_grid(1, 3) => [[2, 2]],
+        one_x_grid(3, 1) => [[2, 2]],
+        one_x_grid(3, 3) => [[2, 2]],
+
+        one_x_grid(1, 2) => [[1, 1], [1, 3], [2, 2], [3, 2]],
+        one_x_grid(2, 1) => [[1, 1], [2, 2], [2, 3], [3, 1]],
+        one_x_grid(2, 3) => [[1, 3], [2, 1], [2, 2], [3, 3]],
+        one_x_grid(3, 2) => [[1, 2], [2, 2], [3, 1], [3, 3]],
+
+        one_x_grid(2, 2) => [[1, 1], [1, 3], [3, 1], [3, 3]]
+      }
+  end
+end

data/lib/xo/ai/minimax.rb

@@ -0,0 +1,125 @@
+require 'ostruct'
+require 'xo/evaluator'
+
+module XO::AI
+
+  def self.minimax(grid, player)
+    state = MaxGameState.new(grid, player)
+    moves = state.next_states.select { |next_state| state.score == next_state.score }.map(&:move)
+
+    OpenStruct.new(start_state: state, moves: moves)
+  end
+
+  class GameState
+
+    attr_reader :grid, :player, :move, :next_states
+
+    def initialize(grid, player, move = nil)
+      @grid   = grid.dup
+      @player = player
+      @move   = move
+
+      generate_next_states
+    end
+
+    def result
+      @result ||= XO::Evaluator.analyze(grid, player)
+    end
+
+    def is_terminal?
+      case result[:status]
+      when :ok
+        false
+      when :game_over
+        true
+      else
+        raise IllegalGridStatusError
+      end
+    end
+
+    def scores
+      next_states.map(&:score)
+    end
+
+    def score
+      if is_terminal?
+        terminal_score
+      else
+        non_terminal_score
+      end
+    end
+
+    def terminal_score
+      raise NotImplementedError
+    end
+
+    def non_terminal_score
+      raise NotImplementedError
+    end
+
+    def next_game_state(next_grid, other_player, move)
+      raise NotImplementedError
+    end
+
+    private
+
+      def generate_next_states
+        @next_states = []
+
+        unless is_terminal?
+          grid.each_free do |r, c|
+            next_grid = grid.dup
+            next_grid[r, c] = player
+
+            @next_states << next_game_state(next_grid, XO.other_player(player), XO::Position.new(r, c))
+          end
+        end
+      end
+  end
+
+  class MaxGameState < GameState
+
+    def next_game_state(next_grid, other_player, move)
+      MinGameState.new(next_grid, other_player, move)
+    end
+
+    def terminal_score
+      case result[:type]
+      when :winner
+        1
+      when :loser
+        -1
+      when :squashed
+        0
+      end
+    end
+
+    def non_terminal_score
+      scores.max
+    end
+  end
+
+  class MinGameState < GameState
+
+    def next_game_state(next_grid, other_player, move)
+      MaxGameState.new(next_grid, other_player, move)
+    end
+
+    def terminal_score
+      case result[:type]
+      when :winner
+        -1
+      when :loser
+        1
+      when :squashed
+        0
+      end
+    end
+
+    def non_terminal_score
+      scores.min
+    end
+  end
+
+  class IllegalGridStatusError < StandardError; end
+end

data/lib/xo/ai/novice.rb

@@ -0,0 +1,11 @@
+require 'xo/ai/expert'
+
+module XO::AI
+
+  class Novice < Expert
+
+    def self.get_moves(grid, player)
+      all_moves
+    end
+  end
+end

data/lib/xo/engine.rb

@@ -0,0 +1,137 @@
+require 'observer'
+require 'ostruct'
+
+require 'xo/grid'
+require 'xo/evaluator'
+
+module XO
+
+  class Engine
+    include Observable
+
+    attr_reader :turn, :state
+
+    def initialize
+      @grid = Grid.new
+      @turn = :nobody
+      @state = :idle
+    end
+
+    def grid
+      @grid.dup
+    end
+
+    def next_turn
+      XO.other_player(turn)
+    end
+
+    def start(player)
+      raise ArgumentError, "unknown player #{player}" unless XO.is_player?(player)
+
+      case state
+      when :idle
+        handle_start(player)
+      else
+        raise NotImplementedError
+      end
+
+      self
+    end
+
+    def stop
+      case state
+      when :playing, :game_over
+        handle_stop
+      else
+        raise NotImplementedError
+      end
+
+      self
+    end
+
+    def play(r, c)
+      case state
+      when :playing
+        handle_play(r.to_i, c.to_i)
+      else
+        raise NotImplementedError
+      end
+
+      self
+    end
+
+    def continue_playing(player)
+      raise ArgumentError, "unknown player #{player}" unless XO.is_player?(player)
+
+      case state
+      when :game_over
+        handle_continue_playing(player)
+      else
+        raise NotImplementedError
+      end
+
+      self
+    end
+
+    private
+
+      attr_writer :turn, :state
+
+      def handle_start(player)
+        self.turn = player
+        self.state = :playing
+        @grid.clear
+
+        send_event(:game_started, who: player)
+      end
+
+      def handle_stop
+        self.state = :idle
+
+        send_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)
+          end
+        else
+          send_event(:invalid_move, type: :out_of_bounds)
+        end
+      end
+
+      def handle_continue_playing(player)
+        self.turn = player
+        self.state = :playing
+        @grid.clear
+
+        send_event(:continue_playing, who: player)
+      end
+
+      def send_event(name, message = {})
+        changed
+        notify_observers({ event: name }.merge(message))
+      end
+  end
+end

data/lib/xo/evaluator.rb

@@ -0,0 +1,108 @@
+module XO
+
+  module Evaluator
+
+    def self.analyze(grid, player)
+      @grid = grid
+      @player = player
+
+      perform_analysis
+    end
+
+    private
+
+      class << self
+        attr_reader :grid, :player, :winners
+      end
+
+      def self.perform_analysis
+        return { status: :error, 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] }
+        else
+          if grid.full?
+            { status: :game_over, type: :squashed }
+          else
+            { status: :ok }
+          end
+        end
+      end
+
+      def self.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
+
+        (xs - os).abs
+      end
+
+      def self.find_winners
+        @winners = {}
+
+        # 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]] })
+        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
+
+        # 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
+
+        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
+      end
+
+      def self.add_winner(player, details)
+        if winners.key?(player)
+          winners[player] << details
+        else
+          winners[player] = [details]
+        end
+      end
+
+      def self.two_winners?
+        winners[XO::X] && winners[XO::O]
+      end
+
+      def self.other_player
+        XO.other_player(player)
+      end
+  end
+end

data/lib/xo/grid.rb

@@ -0,0 +1,95 @@
+module XO
+
+  class Grid
+
+    ROWS = 3
+    COLS = 3
+
+    def self.contains?(r, c)
+      r.between?(1, ROWS) && c.between?(1, COLS)
+    end
+
+    def initialize
+      @grid = Array.new(ROWS * COLS, :e)
+    end
+
+    def initialize_copy(orig)
+      @grid = orig.instance_variable_get(:@grid).dup
+    end
+
+    def []=(r, c, val)
+      if self.class.contains?(r, c)
+        grid[idx(r, c)] = val
+      else
+        raise IndexError, "position (#{r}, #{c}) is off the grid"
+      end
+    end
+
+    def [](r, c)
+      if self.class.contains?(r, c)
+        grid[idx(r, c)]
+      else
+        raise IndexError, "position (#{r}, #{c}) is off the grid"
+      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])
+    end
+
+    def clear
+      grid.fill(:e)
+    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) }
+    end
+
+    def ==(other)
+      return false unless other.instance_of?(self.class)
+      grid == other.instance_variable_get(:@grid)
+    end
+    alias_method :eql?, :==
+
+    def hash
+      grid.hash
+    end
+
+    private
+
+      attr_reader :grid
+
+      # Computes the 0-based index of position (r, c) on a 3x3 grid.
+      #
+      #    c  1   2   3
+      #  r
+      #  1    0 | 1 | 2
+      #      ---+---+---
+      #  2    3 | 4 | 5
+      #      ---+---+---
+      #  3    6 | 7 | 8
+      #
+      # For e.g. idx(2, 3) is 5.
+      def idx(r, c)
+        COLS * (r - 1) + (c - 1)
+      end
+  end
+end

data/lib/xo/version.rb

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

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'minitest/autorun'
+require 'minitest/spec'
+
+require 'xo'

data/spec/xo/ai/minimax_spec.rb

@@ -0,0 +1,63 @@
+require 'spec_helper'
+
+module XO
+
+  describe AI do
+
+    describe 'minimax' do
+
+      let(:grid) { Grid.new }
+
+      describe 'immediate wins' do
+
+        it 'should return (1, 3)' do
+          grid[1, 1] = grid[1, 2] = :x
+          grid[2, 1] = grid[2, 2] = :o
+
+          moves = AI.minimax(grid, :x).moves
+
+          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[2, 1] = grid[2, 3] = grid[3, 1] = :x
+          grid[1, 1] = grid[1, 2] = grid[2, 2] = :o
+
+          moves = AI.minimax(grid, :o).moves
+
+          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
+      end
+
+      describe 'blocking moves' do
+
+        it 'should return (2, 1)' do
+          grid[1, 1] = grid[3, 1] = :x
+          grid[2, 2] = :o
+
+          moves = AI.minimax(grid, :o).moves
+
+          moves.size.must_equal 1
+          [moves[0].row, moves[0].column].must_equal [2, 1]
+        end
+      end
+
+      describe 'smart moves' do
+
+        it 'should return (1, 3)' do
+          grid[1, 1] = grid[3, 1] = :x
+          grid[2, 1] = grid[3, 3] = :o
+
+          moves = AI.minimax(grid, :x).moves
+
+          moves.size.must_equal 1
+          [moves[0].row, moves[0].column].must_equal [1, 3]
+        end
+      end
+    end
+  end
+end

data/spec/xo/engine_spec.rb

@@ -0,0 +1,55 @@
+require 'spec_helper'
+
+module XO
+
+  describe Engine do
+
+    let (:engine) { Engine.new }
+
+    describe 'initial state' do
+
+      it 'has an empty grid' do
+        engine.grid.empty?.must_equal true
+      end
+
+      it "is nobody's turn" do
+        engine.turn.must_equal :nobody
+      end
+
+      it 'is in the idle state' do
+        engine.state.must_equal :idle
+      end
+    end
+
+    describe '#grid' do
+
+      it 'returns a copy' do
+        grid = engine.grid
+        grid[1, 1] = X
+
+        # FIXME: How else can I test this requirement? I don't like that the test
+        # depends on knowing the name of the internal private instance variable.
+        engine.instance_variable_get(:@grid).empty?.must_equal true
+      end
+    end
+
+    describe 'a single round of play' do
+
+      it 'works as follows' do
+        observer = Object.new
+
+        def observer.handle_event(e)
+          if e[:event] == :game_over && e[:type] == :winner
+            @winner = e[:who]
+          end
+        end
+
+        engine.add_observer(observer, :handle_event)
+
+        engine.start(X).play(1, 1).play(2, 1).play(1, 2).play(2, 2).play(1, 3)
+
+        observer.instance_variable_get(:@winner).must_equal X
+      end
+    end
+  end
+end

data/spec/xo/evaluator_spec.rb

@@ -0,0 +1,90 @@
+require 'spec_helper'
+
+module XO
+
+  describe Evaluator do
+
+    describe 'analyze' do
+
+      let (:grid) { Grid.new }
+
+      describe 'error statuses' do
+
+        it 'returns too many moves ahead' do
+          grid[1, 1] = grid[1, 2] = grid[1, 3] = X
+          grid[2, 1] = O
+
+          result = { status: :error, type: :too_many_moves_ahead }
+
+          Evaluator.analyze(grid, X).must_equal result
+          Evaluator.analyze(grid, O).must_equal result
+        end
+
+        it 'returns two winners' do
+          grid[1, 1] = grid[1, 2] = grid[1, 3] = X
+          grid[2, 1] = grid[2, 2] = grid[2, 3] = O
+
+          result = { status: :error, type: :two_winners }
+
+          Evaluator.analyze(grid, X).must_equal result
+          Evaluator.analyze(grid, O).must_equal result
+        end
+      end
+
+      describe 'game over statuses' do
+
+        describe 'wins and losses' do
+
+          it 'returns a win/loss in the first row' do
+            grid[1, 1] = grid[1, 2] = grid[1, 3] = X
+            grid[2, 1] = grid[2, 2] = O
+
+            result = {
+              status: :game_over,
+              type: :winner,
+              details: [{
+                where: :row,
+                index: 1,
+                positions: [[1, 1], [1, 2], [1, 3]]
+              }]
+            }
+
+            Evaluator.analyze(grid, X).must_equal result
+
+            result[:type] = :loser
+            Evaluator.analyze(grid, O).must_equal result
+          end
+
+          # TODO: Test the winners/losers in the other rows, the columns and the diagonals.
+        end
+
+        describe 'squashed' do
+
+          it 'returns squashed' do
+            grid[1, 1] = grid[1, 2] = grid[2, 3] = grid[3, 1] = grid[3, 3] = X
+            grid[1, 3] = grid[2, 1] = grid[2, 2] = grid[3, 2] = O
+
+            result = { status: :game_over, type: :squashed }
+
+            Evaluator.analyze(grid, X).must_equal result
+            Evaluator.analyze(grid, O).must_equal result
+          end
+        end
+      end
+
+      describe 'ok status' do
+
+        it 'returns ok' do
+          result = { status: :ok }
+
+          Evaluator.analyze(grid, X).must_equal result
+          Evaluator.analyze(grid, O).must_equal result
+
+          grid[1, 1] = X
+          Evaluator.analyze(grid, X).must_equal result
+          Evaluator.analyze(grid, O).must_equal result
+        end
+      end
+    end
+  end
+end

data/spec/xo/grid_spec.rb

@@ -0,0 +1,146 @@
+require 'spec_helper'
+
+module XO
+
+  describe Grid do
+
+    it 'has 3 rows' do
+      Grid::ROWS.must_equal 3
+    end
+
+    it 'has 3 columns' do
+      Grid::COLS.must_equal 3
+    end
+
+    it 'contains all r, c where r is in {1, 2, 3} and c is in {1, 2, 3}' do
+      (1..3).each do |r|
+        (1..3).each do |c|
+          Grid.contains?(r, c).must_equal true
+        end
+      end
+    end
+
+    it 'does not contain any r, c where either r is not in {1, 2, 3} or c is not in {1, 2, 3}' do
+      [[0, 0], [0, 1], [0, 2], [0, 3], [0, 4],
+       [1, 0],                         [1, 4],
+       [2, 0],                         [2, 4],
+       [3, 0],                         [3, 4],
+       [4, 0], [4, 1], [4, 2], [4, 3], [4, 4]].each do |pos|
+        Grid.contains?(*pos).must_equal false
+      end
+    end
+
+    let(:grid) { Grid.new }
+
+    describe 'a new grid' do
+
+      it 'is empty' do
+        grid.empty?.must_equal true
+      end
+    end
+
+    describe '#dup' do
+
+      it 'creates a copy' do
+        grid[1, 1] = X
+
+        grid_copy = grid.dup
+        grid_copy[1, 1] = O
+
+        grid[1, 1].must_equal X
+      end
+    end
+
+    describe '#empty?' do
+
+      it 'returns false when at least one position has a token' do
+        grid[1, 1] = X
+        grid.empty?.must_equal false
+      end
+    end
+
+    describe '#[]=' do
+
+      it 'raises IndexError when a token is placed at a position it does not contain' do
+        proc { grid[0, 0] = X }.must_raise IndexError
+      end
+    end
+
+    describe '#[]' do
+
+      it 'raises IndexError when given a position it does not contain' do
+        proc { grid[4, 4] }.must_raise IndexError
+      end
+    end
+
+    describe '#full?' do
+
+      before do
+        (1..3).each do |r|
+          (1..3).each do |c|
+            grid[r, c] = O
+          end
+        end
+      end
+
+      it 'returns true when every position has a token' do
+        grid.full?.must_equal true
+      end
+
+      it 'returns false when at least one position does not have a token' do
+        grid[1, 1] = :e
+        grid.full?.must_equal false
+      end
+    end
+
+    describe '#free?' do
+
+      it 'returns true when no token is at the given position' do
+        grid.free?(2, 2).must_equal true
+      end
+
+      it 'returns false when a token is at the given position' do
+        grid[3, 1] = O
+        grid.free?(3, 1).must_equal false
+      end
+
+      it 'raises IndexError when given a position the grid does not contain' do
+        proc { grid.free?(0, 4) }.must_raise IndexError
+      end
+    end
+
+    describe '#clear' do
+
+      it 'empties the grid' do
+        grid[1, 1] = X
+        grid[1, 3] = O
+        grid[3, 2] = X
+
+        grid.clear
+
+        grid.empty?.must_equal true
+      end
+    end
+
+    describe '#each' do
+
+      it "visits every position and yields a block that takes the position's row, column and value" do
+        grid[1, 1] = O
+        grid[2, 2] = X
+        grid[3, 3] = O
+
+        visited = {}
+
+        grid.each do |r, c, val|
+          # ensure that the value for the position is correct
+          grid[r, c].must_equal val
+
+          # keep track of every position we visit
+          visited[[r, c]] = val
+        end
+
+        visited.keys.size.must_equal(Grid::ROWS * Grid::COLS)
+      end
+    end
+  end
+end

data/xo.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'xo/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'xo'
+  spec.version       = XO::VERSION
+  spec.author        = 'Dwayne R. Crooks'
+  spec.email         = ['me@dwaynecrooks.com']
+  spec.summary       = %q{A Ruby library for Tic-tac-toe.}
+  spec.description   = %q{A Ruby library that can be used to develop Tic-tac-toe game clients.}
+  spec.homepage      = 'https://github.com/dwayne/xo'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rake', '~> 10.1', '>= 10.1.0'
+  spec.add_development_dependency 'minitest', '~> 5.3', '>= 5.3.2'
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: xo
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Dwayne R. Crooks
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.1.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.3.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.3.2
+description: A Ruby library that can be used to develop Tic-tac-toe game clients.
+email:
+- me@dwaynecrooks.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/xo.rb
+- lib/xo/ai.rb
+- lib/xo/ai/advanced_beginner.rb
+- lib/xo/ai/expert.rb
+- lib/xo/ai/minimax.rb
+- lib/xo/ai/novice.rb
+- lib/xo/engine.rb
+- lib/xo/evaluator.rb
+- lib/xo/grid.rb
+- lib/xo/version.rb
+- spec/spec_helper.rb
+- spec/xo/ai/minimax_spec.rb
+- spec/xo/engine_spec.rb
+- spec/xo/evaluator_spec.rb
+- spec/xo/grid_spec.rb
+- xo.gemspec
+homepage: https://github.com/dwayne/xo
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A Ruby library for Tic-tac-toe.
+test_files:
+- spec/spec_helper.rb
+- spec/xo/ai/minimax_spec.rb
+- spec/xo/engine_spec.rb
+- spec/xo/evaluator_spec.rb
+- spec/xo/grid_spec.rb