rora 0.0.5 → 0.0.6

data/README.md

@@ -33,7 +33,7 @@ A complete deck of 52 cards will contain exactly thirteen ranks - numerical valu
 ## Cards
 
 ### Overview
-A playing card is constructed with one suit and one rank. A card can be created in by using the Suit and Rank classes as described above, or their equivalent character values.
+A playing card is constructed with exactly one suit and one rank. A card can be created  by using the Suit and Rank classes as described above, or their equivalent character values.
 
     # Example 1: Creating a card with Rank and Suit instances.
     card = Card.new Rank::ACE, Suit::SPADE
@@ -46,7 +46,7 @@ A playing card is constructed with one suit and one rank. A card can be created
 
 ### Creating multiple cards at once
 
-You can create multiple cards at once by using the to_cards class method. The to_cards takes a series suit-rank characters seperated by commas or white spaces and returns an Array of Cards.
+You can create multiple cards at once by using the to_cards class method. The to_cards takes a series suit-rank characters seperated by commas or white spaces and returns an array of cards.
 
     # Example 1: Create an array of cards by providing a comma-seperated string.
     cards = Card.to_cards "AS,KS,QS,JS"
@@ -60,7 +60,7 @@ You can create multiple cards at once by using the to_cards class method. The to
 ## Hands
 
 ### Overview
-A hand consists of exactly five cards, and can be constructed by providing an Array of cards or an equivalent sequence of suit-rank character values.
+A hand consists of exactly five cards, and can be constructed by providing an array of cards or an equivalent sequence of suit-rank character values.
 
     # Example 1: Creating a hand with a comma-seperated string.
     hand = Hand.new "AS,KS,QS,JS,TS"
@@ -71,7 +71,7 @@ A hand consists of exactly five cards, and can be constructed by providing an Ar
     # Example 3: Creating a hand with an Array of cards.
     hand = Hand.new [Card.new("AS"), Card.new("KS"), Card.new("QS"), Card.new("JS"), Card.new("TS")]
     
-    # Example 4: Creating a hand with an Array of cards, using Card.to_cards
+    # Example 4: Creating a hand with an array of cards, using Card.to_cards
     hand = Hand.new Card.to_cards("AS,KS,QS,JS,TS")
     
 ### Hand Score  
@@ -92,7 +92,7 @@ Each hand in poker has a rank, or score. While many software libraries provide t
     puts seven_high.name => 'High Card'
     puts seven_high.probability => 0.50    // Probability of receiving any High Card
     
-### Hand Detection    
+### Hand Type Detection    
     
 You can query a hand to determine what kind of hand it is.
 
@@ -111,13 +111,20 @@ Hand type detection extends to the following methods:
 - two_pair?
 - one_pair?
 - high_card?
+
+### Hand Type Probability
+
+You can query a hand to determine the probability of drawing that type of hand.
+
+    # Example 1: Determine the probability of a Royal Flush
+    puts Hand.new("AS,KS,QS,JS,TS").probability => 0.0015
     
 ## Starting Hands
 
 Beyond the code samples presented below, the following links provide more information about [texas hold'em starting hands](http://www.moralesce.com/2012/01/21/holdem-starting-hands/) and [poker hand evaluation](http://www.moralesce.com/2011/11/26/poker-hand-evaluation/).
 
 ### Overview
-A starting hand is also referred to as a players pocket cards, or hole cards. A starting hand consists of exactly two cards held by one player, unseen by opponents. Starting hands can be created by proiding an Array of Cards of an equivalent sequence of suit-rank character values.
+A starting hand is also referred to as a player's pocket cards, or hole cards. A starting hand consists of exactly two cards, and can be constructed by providing an array of cards or an equivalent sequence of suit-rank character values.
 
     # Example 1: Creating a starting hand with a comma-seperated string.
     starting_hand = StartingHand.new "AS,KS"
@@ -133,7 +140,9 @@ A starting hand is also referred to as a players pocket cards, or hole cards. A
    
 ### Creating an array of all starting hands
 
-    # Returns an array of all 1324 starting hands.
+Given a deck of 52 cards, choosing any two card yields 1326 distinct 2 card combinations
+
+    # Returns an array of all 1326 starting hands.
     all = StartingHand.all_starting_hands
     
     
@@ -188,27 +197,35 @@ The remove method takes a variety of arguments.
     deck.remove starting_hand
     
 ### Inspecting the Deck
-You can query the deck to determine whether it contains a specific card or at least one card in a group.
-
-    # Determines if the Ace of Spades is in the deck.
-    deck.contains Card.new("AS")    
+You can query the deck to determine whether it contains a specific card or at least one card in a group.  
     
     # Determines if the Ace of Spades is in the deck.
     deck.contains "AS"
     
-    # Determines if any Ace is in the deck.
-    deck.contains [Card.new("AS"), Card.new("AH"), Card.new("AD"), Card.new("AC")]
+    # Determines if the Ace of Spades is in the deck.
+    deck.contains Card.new("AS")
     
     # Determines if any Ace is in the deck.
-    deck.contains "AS,AH,AD,AC"
+    deck.contains_any "AS,AH,AD,AC"
+    
+     # Determines if any Ace is in the deck.
+    deck.contains_any [Card.new("AS"), Card.new("AH"), Card.new("AD"), Card.new("AC")]
+    
+    # Determines if there are any cards in the deck
+    deck.empty?
+    
+    # Returns the number of Aces left in the deck
+    deck.count_cards_with_rank Rank::ACE
+    
+    # Returns the number of Clubs left in the deck
+    deck.count_cards_with_suit Suit::CLUB
     
     
 ### Combinations
 The combination method allows you to enumerate through card subsets. Given a combination value greater than 1, the method will return a two-dimensional array.
 
-
     # Chooses every possible 2 card combination from the deck. Assuming the deck contains 52
-    # cards, this example will return 1324 2-card combinations.
+    # cards, this example will return 1326 2-card combinations.
     cards = deck.combination 2
     
     # Chooses every possible 5 card combination from the deck. Assuming the deck contains 52
@@ -218,7 +235,7 @@ The combination method allows you to enumerate through card subsets. Given a com
 ## Boards
 
 ### Overview
-A board represents the logical table area where community cards are dealt. A board can be setup with either 0, 3, 4 or 5 cards to represent and empty board, the flop, turn, or river (respectively).
+A board represents the logical table area where community cards are dealt. A board can be setup with either 0, 3, 4 or 5 unique cards to represent and empty board, the flop, turn, or river (respectively).
 
     # Creates an empty board.
     board = Board.new
@@ -233,7 +250,7 @@ A board represents the logical table area where community cards are dealt. A boa
     board = Board.new "KS,QS,7H,4C,3H"
     
 ### Subsequent Betting Rounds
-An empty board can be populated afterwads.
+An empty board can be populated after constrution as well - indeed, this is the most common usage.
 
     board = Board.new
     board.flop = "AS,KS,QS"
@@ -252,7 +269,180 @@ You can query the board to determine whether it contains a specific card or at l
     board.contains "AS"
     
     # Determines if any Ace is on the board.
-    board.contains [Card.new("AS"), Card.new("AH"), Card.new("AD"), Card.new("AC")]
+    board.contains_any [Card.new("AS"), Card.new("AH"), Card.new("AD"), Card.new("AC")]
     
     # Determines if any Ace is on the board.
-    board.contains "AS,AH,AD,AC"
+    board.contains_any "AS,AH,AD,AC"
+    
+    # You can query to the board for flop, turn and river cards.
+    puts board.flop => '2H', '3C', 'JH'
+    puts board.turn => 'AS'
+    puts board.river => 'JS'
+    
+    # You can query the board to return all cards on the board
+    puts board.cards => '2H', '3C', 'JH', 'AS', 'JS'
+    
+## Pots
+
+A pot represents the sum of money that players compete for during a hand of poker.
+
+    # Creates a new pot.
+    pot = Pot.new
+    
+### Adding Money to the Pot
+
+You can add positive sums of money to the pot. At the moment the pot assumes only one kind of (implicit) currency.
+
+    # Add money to the pot
+    pot.add(5) 
+    puts pot.value => '5'
+    
+    # Chain add operations
+    pot.add(5).add(5).add(5)
+    puts pot.value => '15'
+    
+    # Add decimal values to the pot
+    pot.add(2.50).add(1.25)
+    puts pot.value => '3.75'
+    
+    # The to_s representation returns formatted monetary amount
+    pot.add(300)
+    puts pot.to_s => '$300.00'
+
+## Tables
+
+A poker table where players compete for pots. A newly created table will have one deck of 52 cards, one  pot with zero dollars and one empty board. You can specify the number of seats at the table - if not provided, a table will be created with 9 seats. A table must have a minimum of 2 seats.
+
+    # Creates a table with 9 seats
+    table = Table.new
+    
+    # Creates a table with 6 seats
+    table = Table.new 6
+    
+### Swapping pots, boards and decks
+
+You can provide a table with different decks, boards and pots. This configuration is chainable, as shown in the example below:
+
+    deck = Deck.new
+    pot = Pot.new
+    board = Board.new
+    …
+    # Creates a table, and configures the table to use the specified board, pot and deck.
+    table = Table.new
+   	table.with(deck).with(board).with(pot)
+   	
+### Managing players
+A poker table won't do us any good unless we have a few players sitting in on a game. We can add players to the table using the add method:
+	
+	table = Table.new
+    james = Player.new("James")
+    sally = Player.new("Sally")
+    
+    # james will automatcially take seat number 1
+    table.add james  
+    
+    # sally will automatcially take seat number 2  
+    table.add sally    
+    
+At a real poker table, players are free to sit at any available seat at the table. You can specify which seat a player sits at:
+
+	table = Table.new
+    james = Player.new("James")
+    sally = Player.new("Sally")
+    
+    # james will sit at seat number 2
+    table.add james 2  
+    
+    # sally will sit at seat number 6
+    table.add sally 6  
+    
+This index is not zero based. In other words, seat 1 is the first seat, you cannot specify to sit at 'seat 0', there's no such thing! If the specified seat is already taken by another player an exception is raised. If the specified seat doesn't exist (you specify to seat a player at seat 11 at a 9-seated table) and exception will be raised.    
+
+You can remove players by using the tables' remove method: 
+
+    # Create a table and a couple of players
+	table = Table.new
+    james = Player.new("James")
+    sally = Player.new("Sally")
+    
+    # james will automatcially take seat number 1
+    table.add james  
+    
+    # james will be removed, seat number 1 will be free
+    table.remove james
+    
+### Inspecting the table
+
+    # Returns the number of seats at the table
+    table.size
+
+    # Determines if all of the seats at the table are occupied
+    table.full?
+    
+    # Determines if none of the seats at the table are occupied
+    table.empty?
+    
+    # Returns all players sitting at the table as an array
+    table.players
+    
+    # Returns seat number 3
+    third_seat = table.seat(3)
+    
+### Poker positions at the table
+
+There are a few positions that are relevant in a poker game, and the rora api makes it trivial to identify key positions. The dealer, or 'button' is a rotating position - after every hand a new dealer is chosen by moving the 'button' or 'puck' in a clockwise fashion around the table.
+
+    # Returns the seat with the button.
+    table.the_button
+
+The small blind sits to the immediate left of the dealer, and is required to post one half sized bet before before a hand begins.
+
+    # Returns the seat with the small blind.
+    table.the_small_blind
+    
+    # In a heads up (2-player) game, the small blind is also the button!
+	table = Table.new
+    james = Player.new("James")
+    sally = Player.new("Sally")
+    
+    puts table.the_button.player.name => 'James'
+    puts table.the_small_blind.player.name => 'James'
+    puts table.the_big_blind.player.name => 'Sally'
+    
+The big blind sits to the immediate left of the small blind, and must post one full sized bet before a hand begins.   
+    
+    # Returns the seat with the big blind.
+    table.the_big_blind 
+    
+UTG sits to the immediate left of the big blind, and is the first player to act in the pre-flop (i.e. first) betting round. The player to the left the big blind is always the first player to act in the preflop betting round. In a heads up (i.e. 2-player game), the 'next' player is our other player, the small blind.
+    
+    # Returns the seat that is first to act, or 'under the gun'
+    table.under_the_gun   
+    
+    # In a heads up (2-player) game, the small blind is also the first to act (under the gun)!
+	table = Table.new
+    james = Player.new("James")
+    sally = Player.new("Sally")
+    
+    puts table.the_small_blind.player.name => 'James'
+    puts table.the_big_blind.player.name => 'Sally'
+    puts table.under_the_gun.player.name => 'James'
+    
+
+### Gaps in player positions
+There is no need for players to sit directly beside each other. Rora maintains an internal linked list of players and their relative positions, so there can be gaps between seated players.
+
+    # Create a table with three players
+	table = Table.new
+    james = Player.new("James")
+    sally = Player.new("Sally")
+    frank  = Player.new("Frank")
+    
+    # Seats 1, 3, 4, 5 and 7 will be unoccupied, that's ok!
+    table.add james 2  
+    table.add sally 6 
+    table.add frank 8
+    
+    puts table.the_small_blind.player.name => 'James'
+    puts table.the_big_blind.player.name => 'Sally'
+    puts table.under_the_gun.player.name => 'Frank'

data/lib/rora/model/board.rb

@@ -65,6 +65,12 @@ class Board
     @river = cd
   end
 
+  # Returns the number of community cards that have been dealt.
+  def size
+    cards.size
+  end
+
+  # Returns the community cards that have been dealt
   def cards
     cds = Array.new
     cds += @flop if !@flop.nil?
@@ -92,4 +98,8 @@ class Board
     false
   end
 
+  def to_s
+    "Board: flop=#{@flop.map { |card| "#{card.key}" }.join(",")}"
+  end
+
 end

data/lib/rora/model/card.rb

@@ -37,10 +37,6 @@ class Card
     @rank.key + @suit.key
   end
 
-  def value
-    @rank.value + @suit.value
-  end
-
   def name
     "#{@rank.value} of #{@suit.value}s"
   end
@@ -68,7 +64,7 @@ class Card
   end
 
   def to_s
-    "Card: name='#{name}' value='#{@rank.key}#{@suit.key}' id=#{id}"
+    "Card: #{name}"
   end
 
 end

data/lib/rora/model/game.rb

@@ -1,8 +1,76 @@
 class Game
-  attr_reader :table, :players, :dealer
+  attr_reader :table, :buy_in, :started
 
-  def initialize
+  def initialize arguments=nil
+    @table = arguments.nil? ? Table.new : (arguments[:table].nil? ? Table.new : arguments[:table])
+    @buy_in = arguments.nil? ? 50 : (arguments[:buy_in].nil ? 20 : arguments[:buy_in])
+    @log = GameLogger.new
+    @started = false
+  end
+
+  def start
+    @started = true
+  end
+
+  def add player
+    raise ArgumentError, "#{player.name} cannot join game, stack of #{player.stack} is less than the buy in amount #{@buy_in}" if player.stack < @buy_in
+    raise ArgumentError, "#{player.name} cannot join game, the game has already started" if @started
+    player.join_game self
+  end
+
+  def remove player
+    player.leave_game
+  end
+
+  def pot
+    @table.pot
+  end
+
+  def shuffle_deck
+    @log.debug("Shuffling the deck")
+    @table.deck.shuffle
+  end
+
+  def assign_button
+    @table.pass_the_buck
+    @log.info("#{@table.the_button.player.name} will be the dealer for this hand");
+  end
+
+  def post_small_blind
+    @table.the_small_blind.player.post_small_blind
+    @log.info("#{@table.the_small_blind.player.name} posts the small blind");
+  end
+
+  def post_big_blind
+    @table.the_big_blind.player.post_big_blind
+    @log.info("#{@table.the_big_blind.player.name} posts the big blind");
+    @log.info("The pot is at #{@table.pot.value}");
+  end
+
+  def deal_pocket_cards
+    @table.players.each do |player|
+      player.add table.deck.deal
+    end
+    @table.players.each do |player|
+      player.add table.deck.deal
+    end
+  end
+
+  def place_bet amount
+    @table.pot.add amount
+  end
+
+  def run_preflop_betting_round
+    @log.info("-----------------------------------------------------------------")
+    first_to_act = @table.under_the_gun
+    first_to_act.player.act
+    number = first_to_act.number
+    seat_number = @table.the_seat_after(first_to_act).number
 
+    while seat_number != number
+      @table.seat(seat_number).player.act
+      seat_number = @table.the_seat_after(@table.seat(seat_number)).number
+    end
   end
 
 end

data/lib/rora/model/hand.rb

@@ -10,12 +10,11 @@
 # hand = Hand.new("ACKCJS9H4H")
 #
 class Hand
-  attr_reader :cards, :hand_repository
+  attr_reader :cards
 
   def initialize cards
     @hand_repository = HandRepository.instance
     @cards = cards.kind_of?(Array) ? cards : Card.to_cards(cards)
-
     raise ArgumentError, "Exactly 5 cards are required to create a hand, #{cards.size} provided" if @cards.size != 5
     raise ArgumentError, "The hand contains duplicate cards" if @cards.uniq.length != @cards.length
   end

data/lib/rora/model/player.rb

@@ -1,8 +1,73 @@
-# To change this template, choose Tools | Templates
-# and open the template in the editor.
-
+#
+# A player in a Texas Hold'em game.
+#
 class Player
-  def initialize
-    
+  attr_reader :name, :stack, :game
+
+  def initialize name, stack
+    raise ArgumentError, "The player name cannot be nil" if name.nil?
+    @name = name
+    @stack = stack.nil? ? 0 : stack
+    @sitting_out = true
+    @table = nil
+    @cards = []
+    @log = GameLogger.new
+  end
+
+  def join_game game, seat=nil
+    raise ArgumentError, "#{@name} cannot join this game, the table is full" if game.table.full?
+    raise ArgumentError, "#{@name} cannot join this game, this player is already playing another game" if !@game.nil?
+    game.table.add self, seat
+    @game = game
+  end
+
+  def leave_game
+    end_session
+    @game = nil
+  end
+
+  def start_session
+    raise ArgumentError, "#{@name} is not sitting at a table" if @game.nil?
+    @sitting_out = false
+  end
+
+  def end_session
+    @sitting_out = true
+  end
+
+  def sitting_out?
+    @sitting_out
+  end
+
+  def add card
+    @cards << card
+  end
+
+  def starting_hand
+    StartingHand.new(@cards)
+  end
+
+  def post_small_blind
+    raise_error_if_sitting_out "cannot post the small blind"
+    @game.place_bet @game.buy_in / 200.00
+  end
+
+  def post_big_blind
+    raise_error_if_sitting_out "cannot post the big blind"
+    @game.place_bet @game.buy_in / 100.00
   end
+
+  def act
+    raise_error_if_sitting_out "cannot act"
+    action = "folds"
+    @log.info("#{name} #{action}")
+  end
+
+  private
+
+  def raise_error_if_sitting_out message
+    raise ArgumentError, "#{name} has not joined a game, #{message}" if game.nil?
+    raise ArgumentError, "#{name} is sitting out, #{message}" if sitting_out?
+  end
+
 end

data/lib/rora/model/pot.rb

@@ -2,20 +2,21 @@
 # The sum of money that players wager during a single hand or game.
 #
 class Pot
-
-  attr_reader :total
+  attr_reader :value
 
   def initialize
-    @total = 0
+    @value = 0
   end
-
+ 
+  # Adds the specified bet to the pot
   def add bet
-    @total += bet
+    raise ArgumentError if bet < 0
+    @value += bet
     self
   end
 
   def to_s
-    "Pot: " + sprintf("$%.02f" , @total)
+    "Pot: " + sprintf("$%.02f" , @value)
   end
 
 end

data/lib/rora/model/rank.rb

@@ -25,11 +25,11 @@ class Rank
     self.values.each do |rank|
       return rank if rank.key.casecmp(key) == 0
     end
-    raise ArgumentError, "No rank exists for key " + key
+    raise ArgumentError, "No rank exists for key '#{key}'"
   end
 
   def to_s
-    "Rank: id=#{@id}, key='#{@key}', value='#{@value}'"
+    "Rank: #{@value}"
   end
 
   class << self

data/lib/rora/model/seat.rb

@@ -0,0 +1,31 @@
+#
+# A seat at a poker table.
+#
+# Once a table is constructed, each seat at the table will contain a reference to
+# the seat before it and the seat after it. In effect, the seat implements a very
+# basic doubly-linked list.
+#
+class Seat
+  attr_accessor :prev, :next, :player, :button
+  attr_reader :number
+
+  def initialize number
+    raise ArgumentError, "Must create a seat number with a value of 1 or greater" if number < 1
+    @number = number
+  end
+
+  # Determines whether the seat is taken.
+  def taken?
+    return !@player.nil?
+  end
+
+  # Determines whether this seat has the dealer button.
+  def button?
+    return !button.nil?
+  end
+
+  def to_s
+    "Seat: #{@number}"
+  end
+
+end

data/lib/rora/model/starting_hand.rb

@@ -99,4 +99,8 @@ class StartingHand
     StartingHandRepository.instance.distinct_starting_hands
   end
 
+  def to_s
+    "StartingHand => " + @cards[0].to_s + ", " + @cards[1].to_s
+  end
+
 end

data/lib/rora/model/suit.rb

@@ -25,7 +25,7 @@ class Suit
   end
 
   def to_s
-    "Suit: id=#{@id}, key='#{@key}', value='#{@value}'"
+    "Suit: #{@value}s"
   end
 
   def == suit