hands 0.0.2 → 0.1.0

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+'lib/**/*.rb'
+-
+Readme.markdown
+Todo.markdown
+LICENSE

data/Gemfile

@@ -2,6 +2,15 @@ source 'https://rubygems.org'
 
 gemspec
 
+# Utility
 gem 'rake'
-gem 'rspec', '~>2.7.0'
-gem 'simplecov', :require => false
+
+# Documentation
+gem 'yard'
+gem 'redcarpet'
+
+group :test do
+  gem 'minitest'
+  gem 'minitest-wscolor'
+  gem 'simplecov'
+end

data/LICENSE

@@ -19,4 +19,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -1,8 +1,12 @@
-#!/usr/bin/env rake
 require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
+require 'rake/testtask'
 
-desc 'Run specs'
-RSpec::Core::RakeTask.new do |t|
-  t.rspec_opts = ['--color']
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+task default: :test
+
+task :coverage do
+  `open coverage/index.html`
 end

data/Readme.markdown

@@ -4,6 +4,8 @@ Simple library for calculating poker hands.
 
 Currently this gem is very limited. I plan on adding outs, odds, and other actually useful stuff. I started writing this on a plane as a personal challenge. It's current state is crude, although tested and works.
 
+[![Dependency Status](https://gemnasium.com/soffes/hands.png)](https://gemnasium.com/soffes/hands)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -22,6 +24,8 @@ Or install it yourself as:
 
 ## Usage
 
+Read the [documentation](http://rubydoc.info/github/samsoffes/hands/master/frames).
+
 ``` ruby
 # Best hand detection
 straight = Hands::Hand.new
@@ -49,8 +53,8 @@ flush << Hands::Card[4, :hearts]
 flush > pair # true
 
 # Card comparison
-card1 = Hands::Card.new(:value => 2, :suite => :hearts)
-card2 = Hands::Card.new(:value => 3, :suite => :clubs)
+card1 = Hands::Card.new(:value => 2, :suit => :hearts)
+card2 = Hands::Card.new(:value => 3, :suit => :clubs)
 card2 > card1 # true
 ```
 
@@ -59,15 +63,15 @@ card2 > card1 # true
 Running and reading the tests is (for now) the best way to see the functionality of this gem.
 
 ```
-$ bundle
-$ bundle exec rake spec
+$ bundle exec rake
 ```
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Write a passing spec
-4. Commit your changes (`git commit -am 'Added some feature'`)
-5. Push to the branch (`git push origin my-new-feature`)
-6. Create new Pull Request
+3. Write passing specs
+4. Write documentation
+5. Commit your changes (`git commit -am 'Added some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create new Pull Request

data/Todo.markdown

@@ -0,0 +1,19 @@
+# Hands Todo
+
+## Features
+
+* Best 5 card hand in hold'em
+* Blinds
+* Betting
+* Missed blinds
+* Outs
+* Odds for completing each hand
+* Pot odds
+* Games other than hold'em
+* AI
+
+## To Document and Test
+
+* Player
+* Table
+* Deck

data/hands.gemspec

@@ -3,10 +3,10 @@ require File.expand_path('../lib/hands/version', __FILE__)
 
 Gem::Specification.new do |gem|
   gem.authors       = ['Sam Soffes']
-  gem.email         = ['sam@samsoff.es']
+  gem.email         = ['sam@soff.es']
   gem.description   = 'Simple library for various poker hands calculations.'
   gem.summary       = 'Simple library for various poker hands calculations.'
-  gem.homepage      = 'http://github.com/samsoffes/hands'
+  gem.homepage      = 'http://github.com/soffes/hands'
 
   gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   gem.files         = `git ls-files`.split("\n")

data/lib/hands.rb

@@ -1,12 +1,21 @@
 require 'hands/version'
 require 'hands/card'
 require 'hands/hand'
+require 'hands/player'
+require 'hands/deck'
+require 'hands/table'
 
+# See <http://www.pagat.com/poker/rules/ranking.html> for ranking references.
 module Hands
-  VALUES = %w{ 2 3 4 5 6 7 8 9 10 j q k a }
+  # All card values
+  VALUES = %w{ 2 3 4 5 6 7 8 9 10 j q k a }.freeze
+
+  # All card value descriptions
   VALUE_DESCRIPTIONS = %w{ two three four five six seven eight nine ten jack queen king ace }
 
-  # Reference: http://www.pagat.com/poker/rules/ranking.html
-  SUITES = %w{ clubs diamonds hearts spades } # Reverse alphabetical
-  HAND_ORDER = %w{ high_card pair two_pair three_of_a_kind straight flush full_house four_of_a_kind straight_flush }
+  # Reverse alphabetically ordered suits
+  SUITES = [:clubs, :diamonds, :hearts, :spades].freeze
+
+  # Ranks of poker hands
+  HAND_ORDER = %w{ high_card pair two_pair three_of_a_kind straight flush full_house four_of_a_kind straight_flush }.freeze
 end

data/lib/hands/card.rb

@@ -1,27 +1,46 @@
 module Hands
+  # Represents a poker playing card.
+  #
+  # You can use `Card[]` as a quick initializer. For example,
+  # `Card[2, :clubs].description` results in `"Two of Clubs"`.
   class Card
     include Comparable
 
-    attr_accessor :suite
+    # @return [Symbol] Card's suit
+    # @see SUITES
+    attr_accessor :suit
+
+    # Card's value
+    #
+    # If an invalid value is set, the value will be set to `nil`.
+    # @return [String] Card's value
+    # @see VALUES
     attr_accessor :value
 
-    def self.[](first = nil, second = nil)
-      self.new(first, second)
+    # (see #initialize)
+    def self.[](value = nil, suit = nil)
+      self.new(value, suit)
     end
 
-    def initialize(first = nil, suite = nil)
+    # Initialize a Card
+    #
+    # @param [String, Integer, Hash] value If an `Integer` or `String` are provided, this will be set to the value. If a `Hash` is provided, its value for `:value` will be set to the `Card`'s value and its `:suit` value will be set to the `Card`'s suit.
+    # @param [Symbol] suit Sets the `Card`'s suit.
+    # @return [Card] A new instance of Card
+    # @see Card.[]
+    def initialize(value = nil, suit = nil)
       # Value provided
-      if first.is_a?(Integer) or first.is_a?(String)
-        self.value = first
+      if value.is_a?(Integer) or value.is_a?(String)
+        self.value = value
 
       # Hash provided
-      elsif first.is_a?(Hash)
-        self.value = first[:value] if first[:value]
-        self.suite = first[:suite] if first[:suite]
+      elsif value.is_a?(Hash)
+        self.value = value[:value] if value[:value]
+        self.suit = value[:suit] if value[:suit]
       end
 
-      # Set suite
-      self.suite = suite if suite
+      # Set suit
+      self.suit = suit if suit
     end
 
     def value=(val)
@@ -29,7 +48,7 @@ module Hands
       if val.is_a?(Integer)
         # Number range
         if val > 0 and val <= 10
-          @value = val
+          @value = val.to_s
           return
 
         # Face card or ace range
@@ -48,6 +67,17 @@ module Hands
       @value = nil
     end
 
+    def suit=(suit)
+      if (suit.is_a?(String) or suit.is_a?(Symbol)) and SUITES.include?(suit.to_sym)
+        @suit = suit.to_sym
+      else
+        @suit = nil
+      end
+    end
+
+    # Standard inspect
+    #
+    # @return [String] `super`'s implementation and the receiver's `description` if it `is_valid?`
     def inspect
       if self.is_valid?
         "#{super} #{self.description}"
@@ -56,35 +86,60 @@ module Hands
       end
     end
 
+    # @return [Boolean] Does the receiver contain a valid value and suit combination
     def is_valid?
-      SUITES.include?(self.suite.to_s) and VALUES.include?(self.value.to_s.downcase)
+      SUITES.include?(@suit) and VALUES.include?(@value.to_s.downcase)
     end
 
+    # @return [Boolean] Does the receiver contain an invalid value and suit combination
     def is_invalid?
       !self.is_valid?
     end
 
+    # Get a string representation of the card
+    #
+    # @return [String] string representation of the card
     def description
       if self.is_valid?
-        "#{VALUE_DESCRIPTIONS[self.value_index].capitalize} of #{self.suite.to_s.capitalize}"
+        "#{VALUE_DESCRIPTIONS[self.value_index].capitalize} of #{self.suit.to_s.capitalize}"
       else
         'invalid'
       end
     end
 
-    def <=>(other_card, check_suite = false)
+    # Compares the card with another card
+    #
+    # By default `check_suit` is `false`. If set to `true`, it will order cards that have the same value by their suit.
+    #
+    # @param [Card] other_card the card to compare the receiver to
+    # @param [Boolean] check_suit a boolean indicating if the suit should be accounted for
+    # @return [Integer] `-1` if `other_card` is less than the receiver, `0` for equal to, and `1` for greater than
+    # @see SUITES
+    def <=>(other_card, check_suit = false)
       # TODO: Handle invalid cards
       result = self.value_index <=> other_card.value_index
-      return self.suite_index <=> other_card.suite_index if result == 0 and check_suite
+      return self.suit_index <=> other_card.suit_index if result == 0 and check_suit
       result
     end
 
-    def suite_index
-      SUITES.index(self.suite.to_s.downcase)
+    # Suite's index
+    #
+    # Mainly used for internal reasons when comparing cards.
+    #
+    # @return [Integer] index of the card's suit
+    # @see SUITES
+    def suit_index
+      SUITES.index(self.suit.downcase)
     end
 
+    # Values's index
+    #
+    # Mainly used for internal reasons when comparing cards.
+    #
+    # @return [Integer] index of the card's value
+    # @see VALUES
     def value_index
-      VALUES.index(self.value.to_s.downcase)
+      VALUES.index(self.value.downcase)
     end
   end
 end

data/lib/hands/deck.rb

@@ -0,0 +1,27 @@
+module Hands
+  class Deck
+    # @return [Array] {Card}s in the {Deck}
+    attr_reader :cards
+
+    # Initialize the deck with 52 {Card}s
+    def initialize
+      @cards = []
+      VALUES.each do |value|
+        SUITES.each do |suit|
+          @cards << Card[value, suit]
+        end
+      end
+    end
+
+    # Shuffle the {Deck}
+    def shuffle!
+      @cards.shuffle!
+    end
+
+    # Pop a card off the {Deck}
+    # @return [Card] the {Card}(s) popped off the {Deck}
+    def pop(number_of_cards = 1)
+      @cards.pop(number_of_cards)
+    end
+  end
+end

data/lib/hands/hand.rb

@@ -1,164 +1,50 @@
+require 'hands/hand_detection'
+
 module Hands
+  # Represents a poker hand.
   class Hand
     include Comparable
 
+    # @return [Array] {Card}s in the {Hand}
     attr_accessor :cards
 
-    def cards
-      @cards ||= []
+    def initialize
+      @cards = []
     end
 
+    # Compares the {Hand} with another {Hand}.
+    #
+    # @param [Hand] other_hand the {Hand} to compare the receiver to
+    # @return [Integer] `-1` if `other_hand` is less than the receiver, `0` for equal to, and `1` for greater than
+    # @see HAND_ORDER
+    # @see Card#<=>
     def <=>(other_hand)
       response = (self.hand_index <=> other_hand.hand_index)
 
-      # If the hands tie, see which is higher (i.e. higher pair)
+      # If the {Hand}s tie, see which is higher (i.e. higher pair)
       if response == 0
-        self.cards <=> other_hand.cards
+        @cards <=> other_hand.cards
       else
         response
       end
     end
 
+    # Add a {Card}
+    #
+    # @return [Card] the {Card} added
     def <<(card)
-      self.cards << card
-    end
-
-    def suites
-      self.cards.collect(&:suite).uniq
-    end
-
-    def best_hand
-      response = {}
-      HAND_ORDER.reverse.each do |type|
-        cards = self.send(type.to_sym)
-        next unless cards
-        response[:type] = type
-        response[:cards] = cards
-        break
-      end
-      response
-    end
-
-    def high_card
-      self.cards.sort.reverse
-    end
-
-    def pair
-      self.pairs(1)
-    end
-
-    def two_pair
-      self.pairs(2)
-    end
-
-    def three_of_a_kind
-      self.kinds(3)
-    end
-
-    def straight
-      return nil unless self.cards.length == 5
-      cs = self.cards.sort.reverse
-
-      # Ace's low
-      if cs.first.value == 'a' and cs[1].value == 5
-        # Move ace to end
-        ace = cs.first
-        cs = cs[1..4]
-        cs << ace
-
-        # Check succession
-        csr = cs.reverse
-        4.times do |i|
-          next if i == 0
-          return nil unless csr[i].value_index == i - 1
-        end
-
-      # Normal
-      else
-        # Check range
-        return nil unless cs.first.value_index - cs.last.value_index == 4
-
-        # Check succession
-        4.times do |i|        
-          return nil unless cs[i].value_index == cs[i + 1].value_index + 1
-        end
-      end
-      cs
-    end
-
-    def flush
-      # If all of the cards are the same suite, we have a flush
-      return nil unless self.suites.length == 1
-      self.cards.sort.reverse
-    end
-
-    def full_house
-      dupes = self.duplicates
-      return nil unless dupes.length == 2
-
-      a = []
-      b = []
-
-      hand = self.cards.select do |card|
-        if dupes.first == card.value
-          a << card
-        elsif dupes.last == card.value
-          b << card
-        end
-      end
-
-      return nil unless a.length + b.length == 5
-      self.cards.sort.reverse
-    end
-
-    def four_of_a_kind
-      self.kinds(4)
+      @cards << card
+      @cards.flatten! # TODO: Figure out why this is necessary
     end
 
-    def straight_flush
-      return nil unless self.flush
-      self.straight
-    end
-
-    protected
-
-    def hand_index
-      best = self.best_hand
-      return -1 if best.nil?
-      HAND_ORDER.index(best[:type].to_s)
+    # @return [Array] All of the suits contained in the {Hand}
+    def suits
+      @cards.collect(&:suit).uniq
     end
 
-    def duplicates
-      pairs = self.cards.collect(&:value)
-      pairs.uniq.select{ |e| (pairs - [e]).size < pairs.size - 1 }
-    end
-
-    def pairs(min)
-      dupes = self.duplicates
-      return nil if dupes.length < min
-
-      hand = self.cards.select do |card|
-        dupes.include?(card.value)
-      end
-
-      hand = hand.sort.reverse
-      hand << (self.cards - hand).sort.reverse
-      hand.flatten
-    end
-
-    def kinds(num)
-      dupes = self.duplicates
-      return nil unless dupes.length == 1
-
-      hand = self.cards.select do |card|
-        dupes.include?(card.value)
-      end
-
-      return nil unless hand.length == num
-
-      hand = hand.sort.reverse
-      hand << (self.cards - hand).sort.reverse
-      hand.flatten
+    # Empties the hand
+    def empty!
+      @cards = []
     end
   end
 end