xo 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: f4e9916b4a489801329e2b8713a883a06ebef55f
-  data.tar.gz: 83ea35a8950526c5ab4a10587ac151ce3523f6d6
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTMyNzA0ODhkYmI4OGE5ZjM3ZDc3YjZkNDA2NGQ0ZWZjMWI3ODYwYQ==
+  data.tar.gz: !binary |-
+    OWNlNjMxM2JmMDEzMTQ0YWJjNjdjMDUzYmQ0ZDQ3YmY3OWUzMDk4OA==
 SHA512:
-  metadata.gz: ff7f19ed461e17028efaeda45010b6faf967103640d004b80da343f179dd4dbf307577aeebfb38bcfeda61f33c01b45657ea5ceadd911c7ca134496d6ff532b5
-  data.tar.gz: e31c7c082b239cd9e3efc10edb36e9e92197e383b4da15f84f8a9d6520fa55c72ccbaa743d3e0aa1fe224f4260bf2c8e4327b57d564eaa1aea8148dd310aa06b
+  metadata.gz: !binary |-
+    OGY3M2IyNWE0Y2YzYzZkMzlhMmEzNzIyODg3YTFiNzg1MzFiMjZkZDBiMjZl
+    OWMzYzllZjVhYTVjOWM1NTYxY2MyYWQ3ODdlZDhmNzUxMjNlNTA0N2VhYzQ2
+    MjE4OWJhNGE0NTk3YTFiYTU3MWViMjAxODcxZGQ0OGFiYjAwMGU=
+  data.tar.gz: !binary |-
+    ZjllZDA0YzY0MDYzMTVlY2EzMzlkZmE4NjU2ZjEzNDYwOTJiM2EwNDYyNmI0
+    YTRlZWRlOWM0N2MyNjFkM2FhYmU0MTJlNzA5NDVhMjFmZjk0OTQ0NTMzYzYx
+    Yzk2ZjFmNzAyY2JlNzY0OWM3OTEyMTNkYjkyOTBiMTcwNGJjZDQ=

data/.gitignore

@@ -1 +1,5 @@
 *.gem
+.ruby-gemset
+.ruby-version
+.yardoc
+/coverage

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    xo (0.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coveralls (0.7.0)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
+    docile (1.1.3)
+    mime-types (2.2)
+    minitest (5.3.3)
+    multi_json (1.10.0)
+    rake (10.3.1)
+    redcarpet (3.1.1)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
+    thor (0.19.1)
+    tins (1.1.0)
+    yard (0.8.7.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  coveralls (~> 0.7)
+  minitest (~> 5.3)
+  rake (~> 10.3)
+  redcarpet (~> 3.1)
+  xo!
+  yard (~> 0.8)

data/README.md

@@ -1,55 +1,120 @@
 # xo
 
+[![Gem Version](https://badge.fury.io/rb/xo.svg)](http://badge.fury.io/rb/xo)
+[![Build Status](https://travis-ci.org/dwayne/xo.svg?branch=master)](https://travis-ci.org/dwayne/xo)
+[![Coverage Status](https://coveralls.io/repos/dwayne/xo/badge.png)](https://coveralls.io/r/dwayne/xo)
+[![Code Climate](https://codeclimate.com/github/dwayne/xo.png)](https://codeclimate.com/github/dwayne/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
+The code is well documented and fully tested, so please have a [read of the documentation](http://rubydoc.info/github/dwayne/xo) and have a [look at the tests](https://github.com/dwayne/xo/tree/master/spec/xo).
+
+My implementation of the [Minimax algorithm](http://en.wikipedia.org/wiki/Minimax#Minimax_algorithm_with_alternate_moves) might be a little different than what you've seen before. It uses symmetry to significantly reduce the search space and in so doing we get good [performance out of the algorithm](#Performance_of_the_Minimax_Algorithm). However, I still want to get it under 1 second. I'd love to get your thoughts on how I can make it happen. Have a [look](https://github.com/dwayne/xo/blob/master/lib/xo/ai/minimax.rb#L23).
+
+## Installation
+
+```
+$ gem install xo
+```
+
+## Example usage
+
+Managing the grid yourself.
 
 ```ruby
-require 'benchmark'
 require 'xo'
 
-# Empty grid
-g = XO::Grid.new
+include XO
+
+g = Grid.new('xx oo')
+
+puts g # =>  x | x |
+       #    ---+---+---
+       #     o | o |
+       #    ---+---+---
+       #       |   |
+
+Evaluator.analyze(g, Grid::X) # => { status: :ok }
+
+g[1, 3] = Grid::X
+Evaluator.analyze(g, Grid::X) # => { status: :game_over,
+                              #      type: :winner,
+                              #      details: [{
+                              #        where: :row,
+                              #        index: 1,
+                              #        positions: [[1, 1], [1, 2], [1, 3]]
+                              #      }]
+                              #    }
+
+Evaluator.analyze(g, Grid::O) # => { status: :game_over,
+                              #      type: :loser,
+                              #      details: [{
+                              #        where: :row,
+                              #        index: 1,
+                              #        positions: [[1, 1], [1, 2], [1, 3]]
+                              #      }]
+                              #    }
+```
+
+The problem with managing the grid yourself is that there is nothing stopping you from making bad moves. For example, playing twice.
+
+```ruby
+g = Grid.new('xx')
+Evaluator.analyze(g, Grid::O) # => { status: :invalid_grid,
+                              #      type: :too_many_moves_ahead
+                              #    }
+```
 
-puts Benchmark.measure { XO::AI.minimax(g, :x) }
-# => 0.000000   0.000000   0.000000 (  0.000463)
-# => O(1) time due to caching
+To avoid such situations, let the engine handle game play. Once you tell it who plays first, then it ensures that the game play follows the rules of [Tic-tac-toe](http://en.wikipedia.org/wiki/Tic-tac-toe).
 
-# One spot taken
-g[1, 1] = :x
+```ruby
+e = Engine.new
+e.start(Grid::O).play(2, 1).play(1, 1).play(2, 2).play(1, 2).play(2, 3)
+e.last_event # => { name: :game_over,
+             #      type: :winner,
+             #      last_move: { turn: :o, r: 2, c: 3 },
+             #      details: [{
+             #        where: :row,
+             #        index: 2,
+             #        positions: [[2, 1], [2, 2], [2, 3]]
+             #      }]
+             #    }
+```
 
-puts Benchmark.measure { XO::AI.minimax(g, :o) }
-# => 0.000000   0.000000   0.000000 (  0.000216)
-# => O(1) time due to caching
+I also built a [Tic-tac-toe](http://en.wikipedia.org/wiki/Tic-tac-toe) command-line client that uses the library. See how everything comes together by viewing its implementation right [here](https://github.com/dwayne/xo/blob/master/bin/xo).
 
-# Two spots taken
-g[1, 3] = :o
+To use the [client](https://github.com/dwayne/xo/blob/master/bin/xo) just type,
 
-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
+```
+$ xo
 ```
 
-# Testing
+on the command-line after installing the gem.
 
-You can run:
+## Performance of the Minimax Algorithm
 
-- All tests: `rake test`
-- One test: `ruby -Ilib -Ispec spec/path_to_spec_file.rb`
+```ruby
+require 'benchmark'
+require 'xo/ai/minimax'
+
+puts Benchmark.measure { XO::AI::Minimax.instance }
+# => 3.090000   0.000000   3.090000 (  3.091686)
+```
+
+## Testing
 
-# TODO
+You can run:
 
-1. Write documentation.
-2. Show example usage.
-3. Write an example Tic-tac-toe command-line game client.
+- All specs: `bundle exec rake`, or
+- A specific spec: `bundle exec ruby -Ilib -Ispec spec/path_to_spec_file.rb`
 
-# Contributing
+## 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
+## 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

@@ -5,3 +5,5 @@ Rake::TestTask.new do |t|
   t.pattern = 'spec/**/*_spec.rb'
   t.libs.push 'spec'
 end
+
+task default: :test

data/bin/xo

@@ -0,0 +1,314 @@
+#!/usr/bin/env ruby
+#
+# A Tic-tac-toe game client based on xo.
+
+require 'xo'
+include XO
+
+AUTHOR = "Dwayne Crooks"
+EMAIL  = "me@dwaynecrooks.com"
+
+class Player
+
+  def moves(grid, turn)
+    raise NotImplementedError
+  end
+
+  private
+
+    def all_open_moves(grid)
+      moves = []
+
+      grid.each_open do |r, c|
+        moves << [r, c]
+      end
+
+      moves
+    end
+
+    def all_smart_moves(grid, turn)
+      AI::Minimax.instance.moves(grid, turn)
+    end
+end
+
+class Easy < Player
+
+  def moves(grid, turn)
+    all_open_moves(grid)
+  end
+end
+
+class Medium < Player
+
+  def moves(grid, turn)
+    smart_moves = all_smart_moves(grid, turn)
+    dumb_moves = all_open_moves(grid) - smart_moves
+
+    dumb_moves.empty? ? smart_moves : (rand < 0.75 ? smart_moves : dumb_moves)
+  end
+end
+
+class Hard < Player
+
+  def moves(grid, turn)
+    all_smart_moves(grid, turn)
+  end
+end
+
+class Human
+
+  def initialize(humans)
+    @humans = humans
+  end
+
+  def get_move(grid, turn)
+    puts grid
+    puts
+
+    puts "Enter your move in the format r, c."
+    prompt_for_move(grid, turn)
+  end
+
+  def handle_next_turn(grid)
+    puts grid
+    puts
+  end
+
+  def handle_game_over(grid, event)
+    case event[:type]
+    when :winner
+      puts "Congratulations! #{@humans == 2 ? event[:last_move][:turn] : 'You'} won."
+    when :squashed
+      puts "Sorry! Game squashed."
+    end
+
+    puts
+  end
+
+  def handle_invalid_move(event)
+    puts "Sorry! You cannot make that move."
+
+    case event[:type]
+    when :occupied
+      puts "That position is occupied."
+    when :out_of_bounds
+      puts "That position is not on the board."
+    end
+
+    puts
+  end
+
+  private
+
+    def prompt_for_move(grid, turn)
+      print "> "
+
+      position = gets.chomp.split(',').map(&:strip).map(&:to_i)
+
+      if position.length == 2
+        puts
+        position
+      else
+        prompt_for_move(grid, turn)
+      end
+    end
+end
+
+class Computer
+
+  def initialize(humans, ai)
+    @humans = humans
+    @ai = ai
+  end
+
+  def get_move(grid, turn)
+    puts "Waiting for the computer to play..." if @humans == 1
+
+    r, c = @ai.moves(grid, turn).shuffle[0]
+
+    if @humans == 1
+      puts "The computer played at #{r}, #{c}."
+      puts
+    end
+
+    [r, c]
+  end
+
+  def handle_next_turn(grid)
+  end
+
+  def handle_game_over(grid, event)
+    if @humans == 0
+      case event[:type]
+      when :winner
+        puts "#{event[:last_move][:turn]} wins!"
+      when :squashed
+        puts "Game squashed!"
+      end
+    elsif @humans == 1
+      puts grid
+      puts
+
+      case event[:type]
+      when :winner
+        puts "Sorry! You lost."
+      when :squashed
+        puts "Sorry! Game squashed."
+      end
+
+      puts
+    end
+  end
+
+  def handle_invalid_move(event)
+  end
+end
+
+class Game
+
+  def initialize(players)
+    @players = players
+    @engine = Engine.new
+  end
+
+  def start(turn = false)
+    if turn
+      @engine.start(turn)
+    else
+      event = @engine.last_event
+
+      case event[:type]
+      when :winner
+        @engine.continue_playing(@engine.turn)
+      when :squashed
+        @engine.continue_playing(@engine.next_turn)
+      end
+    end
+  end
+
+  def run
+    run_one_turn while @engine.state != :game_over
+  end
+
+  private
+
+    def run_one_turn
+      turn = @engine.turn
+      player = @players[turn]
+
+      r, c = player.get_move(@engine.grid, turn)
+
+      event = @engine.play(r, c).last_event
+
+      case event[:name]
+      when :next_turn
+        player.handle_next_turn(@engine.grid)
+      when :game_over
+        player.handle_game_over(@engine.grid, event)
+      when :invalid_move
+        player.handle_invalid_move(event)
+      end
+    end
+end
+
+def welcome
+  heading = "Welcome to xo! A Tic-tac-toe game client created by #{AUTHOR}."
+
+  puts heading
+  puts "=" * heading.length
+  puts
+
+  puts "NOTE: You can exit the game at anytime by pressing CTRL-C."
+  puts
+end
+
+def ask_for_difficulty_level
+  puts "Please select your difficulty level:"
+  puts "1. Easy"
+  puts "2. Medium"
+  puts "3. Hard"
+
+  get_option({ '1' => Easy, '2' => Medium, '3' => Hard })
+end
+
+def ask_for_token
+  puts "Do you want to play as x or o?"
+
+  get_option({ 'x' => Grid::X, 'o' => Grid::O })
+end
+
+def ask_to_play_first
+  puts "Do you want to play first (y or n)?"
+
+  get_option({ 'y' => true, 'n' => false })
+end
+
+def ask_to_play_again
+  puts "Do you want to play again (y or n)?"
+
+  get_option({ 'y' => true, 'n' => false })
+end
+
+def get_option(options)
+  print "> "
+
+  selection = gets.chomp
+
+  if options.key?(selection)
+    puts
+    options[selection]
+  else
+    get_option(options)
+  end
+end
+
+def say_goodbye
+  puts "Thank you for playing."
+  puts "Bye!"
+end
+
+def terminate
+  puts
+  puts
+  say_goodbye
+  exit
+end
+
+def set_up_ctrl_c_handler
+  trap("INT") {
+    terminate
+  }
+end
+
+def main
+  set_up_ctrl_c_handler
+
+  welcome
+
+  level = ask_for_difficulty_level
+
+  human_token = ask_for_token
+  computer_token = Grid.other_token(human_token)
+
+  play_first = ask_to_play_first
+
+  players = {}
+  players[human_token] = Human.new(1)
+  players[computer_token] = Computer.new(1, level.new)
+
+  game = Game.new(players)
+  game.start(play_first ? human_token : computer_token)
+
+  loop do
+    game.run
+
+    play_again = ask_to_play_again
+    break unless play_again
+
+    game.start
+  end
+
+  say_goodbye
+end
+
+main