ruby-poker 0.3.2 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9070959501edf045c9d745325c51573314ecbc11
+  data.tar.gz: 8616e190cbcce32c2ad4f9455df760f0649fbb59
+SHA512:
+  metadata.gz: f0dae2e671b57b3c98d092b200544b8e4423adedf4d66a4c360f202e2df39b9ef96f1e62b66286c1a78d1bd8f2cbd4f335df2c8831bffbd14fbccf292bc6a0ba
+  data.tar.gz: deb4dba594571df9ec74a1b368f11d86e10db12003bc849cecf19810eed73d94c252d14c4d77354332399d3876dfb2c5bfd3ef0b8346d0badc893019ddf001bc

data/CHANGELOG

@@ -1,3 +1,8 @@
+2013-12-28 (1.0.0)
+    * Add Gemfile
+    * Add "Empty Hand" rank for empty hands. Fixes #1.
+    * Simplify internal calculation of `value` in Card class. Fixes #2.
+
 2009-07-12 (0.3.2)
     * Reorganized ruby-poker's lib folder to match the standard layout for gems. This makes ruby-poker compatible with Rip.
     * Bug [#26276] improper two_pair? behavior. Applied patch by Uro.
@@ -6,7 +11,7 @@
 
 2009-01-24 (0.3.1)
     * Bug [#23623] undefined method <=> for nil:NilClass
-    
+
 2008-12-30 (0.3.1)
     * Bug (#20407) Raise an exception when creating a new hand with duplicates
     * Added PokerHand#uniq method
@@ -18,34 +23,34 @@
     * Bug [#20196] 'rank' goes into an infinite loop.
     * Bug [#20195] Allows the same card to be entered into the hand.
     * Bug [#20344] sort_using_rank does not return expected results
-    
+
 2008-04-20 (0.2.4)
     * Modernized the Rakefile
     * Updated to be compatible with Ruby 1.9    
-    
+
 2008-04-06 (0.2.2)
     * Fixed bug where two hands that had the same values but different suits returned not equal    
-    
+
 2008-02-08 (0.2.1)
     * Cards can be added to a hand after it is created by using (<<) on a PokerHand
     * Cards can be deleted from a hand with PokerHand.delete()
-    
+
 2008-01-21 (0.2.0)
     * Merged Patrick Hurley's poker solver
     * Added support for hands with >5 cards
     * Straights with a low Ace count now
     * to_s on a PokerHand now includes the rank after the card list
     * Finally wrote the Unit Tests suite      
-    
+
 2008-01-12 (0.1.2)
-    * Fixed critical bug that was stopping the whole program to not work
+    * Fixed critical bug that was causing the whole program to not work
     * Added some test cases as a result
     * More test cases coming soon      
-    
+
 2008-01-12 (0.1.1)
     * Ranks are now a class.
     * Extracted card, rank, and arrays methods to individual files
     * Added gem packaging
-        
+
 2008-01-10 (0.1.0)
     * Initial version

data/README.rdoc

@@ -1,9 +1,9 @@
 = Poker library in Ruby
 ===
 
-Author:: {Rob Olson}[http://thinkingdigitally.com]
+Author:: {Rob Olson}[https://github.com/robolson]
 Email:: [first name] [at] thinkingdigitally.com
-GitHub:: http://github.com/robolson/ruby-poker
+GitHub:: https://github.com/robolson/ruby-poker
 
 == Description
 
@@ -13,13 +13,13 @@ Card representations can be passed to the PokerHand constructor as a string or a
 
 == Install
 
-    sudo gem install ruby-poker
+    gem install ruby-poker
 
 == Example
 
     require 'rubygems'
     require 'ruby-poker'
-    
+
     hand1 = PokerHand.new("8H 9C TC JD QH")
     hand2 = PokerHand.new(["3D", "3C", "3S", "KD", "AH"])
     puts hand1                => 8h 9c Tc Jd Qh (Straight)
@@ -34,12 +34,16 @@ Card representations can be passed to the PokerHand constructor as a string or a
 By default ruby-poker will not raise an exception if you add the same card to a hand twice. You can tell ruby-poker to not allow duplicates by doing the following
 
     PokerHand.allow_duplicates = false
-    
+
 Place that line near the beginning of your program. The change is program wide so once allow_duplicates is set to false, _all_ poker hands will raise an exception if a duplicate card is added to the hand.
 
 == Compatibility
 
-Ruby-Poker is compatible with Ruby 1.8.6 and Ruby 1.9.1.
+Ruby-Poker is compatible with Ruby 1.8, Ruby 1.9, Ruby 2.0.
+
+== RDoc
+
+View the {generated documentation for ruby-poker}[http://rdoc.info/gems/ruby-poker/frames] on rdoc.info.
 
 == History
 
@@ -47,4 +51,4 @@ In the 0.2.0 release Patrick Hurley's Texas Holdem code from http://www.rubyquiz
 
 == License
 
-This is free software; you can redistribute it and/or modify it under the terms of the BSD license. See LICENSE for more details.
+This is free software; you can redistribute it and/or modify it under the terms of the BSD license. See LICENSE for more details.

data/Rakefile

@@ -1,70 +1,9 @@
-require 'rubygems'
-require 'rake'
-
-begin
-  require 'metric_fu'
-rescue LoadError
-end
-
-RUBYPOKER_VERSION = "0.3.2"
-
-spec = Gem::Specification.new do |s|
-  s.name     = "ruby-poker"
-  s.version  = RUBYPOKER_VERSION
-  s.date     = "2009-07-27"
-  s.rubyforge_project = "rubypoker"
-  s.platform = Gem::Platform::RUBY
-  s.summary = "Poker library in Ruby"
-  s.description = "Ruby library for comparing poker hands and determining the winner."
-  s.author  = "Rob Olson"
-  s.email    = "rob@thinkingdigitally.com"
-  s.homepage = "http://github.com/robolson/ruby-poker"
-  s.has_rdoc = true
-  s.files    = ["CHANGELOG", 
-                "examples/deck.rb", 
-                "examples/quick_example.rb", 
-                "lib/ruby-poker.rb",
-                "lib/ruby-poker/card.rb", 
-                "lib/ruby-poker/poker_hand.rb", 
-                "LICENSE", 
-                "Rakefile", 
-                "README.rdoc", 
-                "ruby-poker.gemspec"]
-  s.test_files = ["test/test_helper.rb", "test/test_card.rb", "test/test_poker_hand.rb"]
-  s.require_paths << 'lib'
-
-  s.extra_rdoc_files = ["README.rdoc", "CHANGELOG", "LICENSE"]
-  s.rdoc_options << '--title' << 'Ruby Poker Documentation' <<
-                    '--main'  << 'README.rdoc' <<
-                    '--inline-source' << '-q'
-
-  s.add_development_dependency('thoughtbot-shoulda', '> 2.0.0')
-end
-
-require 'rake/gempackagetask'
-Rake::GemPackageTask.new(spec) do |pkg| 
-  pkg.need_tar = true 
-  pkg.need_zip = true
-end
-
 require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.verbose = true
-  test.warning = true
-end
-
-desc "Start autotest"
-task :autotest do
-  ruby "-I lib -w /usr/bin/autotest"
-end
-
-require 'rake/rdoctask'
-Rake::RDocTask.new(:docs) do |rdoc|
-  rdoc.main     = 'README.rdoc'
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = "Ruby Poker #{RUBYPOKER_VERSION}"
-  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG', 'LICENSE', 'lib/**/*.rb')
+Rake::TestTask.new do |t|
+  t.libs = ['lib']
+  t.verbose = true
+  t.warning = true
+  t.test_files = FileList['test/test_card.rb', 'test/test_poker_hand.rb']
 end
 
-task :default => :test
+task :default => :test

data/examples/deck.rb

@@ -10,7 +10,7 @@ class Deck
     end
     shuffle
   end
-  
+
   def shuffle
     @cards = @cards.sort_by { rand }
     return self
@@ -21,7 +21,7 @@ class Deck
   def deal
     @cards.pop
   end
-  
+
   # delete an array or a single card from the deck
   # converts a string to a new card, if a string is given
   def burn(burn_cards)
@@ -29,7 +29,7 @@ class Deck
     if burn_cards.is_a?(Card) || burn_cards.is_a?(String)
       burn_cards = [burn_cards]
     end
-    
+
     burn_cards.map! do |c|
       c = Card.new(c) unless c.class == Card
       @cards.delete(c)

data/lib/ruby-poker.rb

@@ -1,3 +1,2 @@
-$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__))   # For use/testing when no gem is installed
 require 'ruby-poker/card'
 require 'ruby-poker/poker_hand'

data/lib/ruby-poker/card.rb

@@ -8,98 +8,98 @@ class Card
     's' => 3
   }
   FACE_VALUES = {
-    'L' =>  1,   # this is a magic low ace
-    '2' =>  2,
-    '3' =>  3,
-    '4' =>  4,
-    '5' =>  5,
-    '6' =>  6,
-    '7' =>  7,
-    '8' =>  8,
-    '9' =>  9,
-    'T' => 10,
-    'J' => 11,
-    'Q' => 12,
-    'K' => 13,
-    'A' => 14
+    'L' =>  0,   # this is a low ace
+    '2' =>  1,
+    '3' =>  2,
+    '4' =>  3,
+    '5' =>  4,
+    '6' =>  5,
+    '7' =>  6,
+    '8' =>  7,
+    '9' =>  8,
+    'T' =>  9,
+    'J' => 10,
+    'Q' => 11,
+    'K' => 12,
+    'A' => 13
   }
 
   def Card.face_value(face)
-    face.upcase!
-    if face == 'L' || !FACE_VALUES.has_key?(face)
-      nil
-    else
-      FACE_VALUES[face] - 1
-    end
+    FACE_VALUES[face.upcase]
   end
 
   private
-  
-  def build_from_value(value)
-    @value = value
-    @suit  = value / FACES.size()
-    @face  = (value % FACES.size())
+
+  def build_from_value(given_value)
+    @suit  = given_value / 13
+    @face  = given_value % 13
   end
 
   def build_from_face_suit(face, suit)
     suit.downcase!
     @face  = Card::face_value(face)
     @suit  = SUIT_LOOKUP[suit]
-    @value = (@suit * FACES.size()) + (@face - 1)
+    raise ArgumentError, "Invalid card: \"#{face}#{suit}\"" unless @face and @suit
   end
 
-  def build_from_face_suit_values(face, suit)
-    build_from_value((face - 1) + (suit * FACES.size()))
+  def build_from_face_suit_values(face_int, suit_int)
+    @face = face_int
+    @suit = suit_int
   end
-  
+
   def build_from_string(card)
     build_from_face_suit(card[0,1], card[1,1])
   end
-  
+
   # Constructs this card object from another card object
   def build_from_card(card)
-    @value = card.value
     @suit = card.suit
     @face = card.face
   end
-  
+
   public
 
-  def initialize(*value)
-    if (value.size == 1)
-      if (value[0].respond_to?(:to_card))
-        build_from_card(value[0])
-      elsif (value[0].respond_to?(:to_str))
-        build_from_string(value[0])
-      elsif (value[0].respond_to?(:to_int))
-        build_from_value(value[0])
+  def initialize(*args)
+    if (args.size == 1)
+      arg = args.first
+      if (arg.respond_to?(:to_card))
+        build_from_card(arg)
+      elsif (arg.respond_to?(:to_str))
+        build_from_string(arg)
+      elsif (arg.respond_to?(:to_int))
+        build_from_value(arg)
       end
-    elsif (value.size == 2)
-      if (value[0].respond_to?(:to_str) &&
-          value[1].respond_to?(:to_str))
-        build_from_face_suit(value[0], value[1])
-      elsif (value[0].respond_to?(:to_int) &&
-             value[1].respond_to?(:to_int))
-        build_from_face_suit_values(value[0], value[1])
+    elsif (args.size == 2)
+      arg1, arg2 = args
+      if (arg1.respond_to?(:to_str) &&
+          arg2.respond_to?(:to_str))
+        build_from_face_suit(arg1, arg2)
+      elsif (arg1.respond_to?(:to_int) &&
+             arg2.respond_to?(:to_int))
+        build_from_face_suit_values(arg1, arg2)
       end
     end
   end
 
-  attr_reader :suit, :face, :value
+  attr_reader :suit, :face
   include Comparable
 
+  def value
+    (@suit * 13) + @face
+  end
+
   # Returns a string containing the representation of Card
   #
   # Card.new("7c").to_s                   # => "7c"
   def to_s
     FACES[@face].chr + SUITS[@suit].chr
   end
-  
+
   # If to_card is called on a `Card` it should return itself
   def to_card
     self
   end
-  
+
   # Compare the face value of this card with another card. Returns:
   # -1 if self is less than card2
   # 0 if self is the same face value of card2
@@ -107,20 +107,20 @@ class Card
   def <=> card2
     @face <=> card2.face
   end
-  
+
   # Returns true if the cards are the same card. Meaning they
   # have the same suit and the same face value.
   def == card2
-    @value == card2.value
+    value == card2.value
   end
   alias :eql? :==
-  
+
   # Compute a hash-code for this Card. Two Cards with the same
-  # content will have the same hash code (and will compare using eql?). 
+  # content will have the same hash code (and will compare using eql?).
   def hash
-    @value.hash
+    value.hash
   end
-  
+
   # A card's natural value is the closer to it's intuitive value in a deck
   # in the range of 1 to 52. Aces are low with a value of 1. Uses the bridge
   # order of suits: clubs, diamonds, hearts, and spades. The formula used is:

data/lib/ruby-poker/poker_hand.rb

@@ -1,32 +1,34 @@
 class PokerHand
   include Comparable
+  include Enumerable
   attr_reader :hand
-  
+
   @@allow_duplicates = true    # true by default
   def self.allow_duplicates; @@allow_duplicates; end
   def self.allow_duplicates=(v); @@allow_duplicates = v; end
-  
+
   # Returns a new PokerHand object. Accepts the cards represented
   # in a string or an array
   #
   #     PokerHand.new("3d 5c 8h Ks")   # => #<PokerHand:0x5c673c ...
   #     PokerHand.new(["3d", "5c", "8h", "Ks"])  # => #<PokerHand:0x5c2d6c ...
   def initialize(cards = [])
-    if cards.is_a? Array
-      @hand = cards.map do |card|
+    @hand = case cards
+    when Array
+      cards.map do |card|
         if card.is_a? Card
           card
         else
           Card.new(card.to_s)
         end
       end
-    elsif cards.respond_to?(:to_str)
-      @hand = cards.scan(/\S{2,3}/).map { |str| Card.new(str) }
+    when String
+      cards.scan(/\S{2}/).map { |str| Card.new(str) }
     else
-      @hand = cards
+      cards
     end
-    
-    check_for_duplicates if !@@allow_duplicates
+
+    check_for_duplicates unless allow_duplicates
   end
 
   # Returns a new PokerHand object with the cards sorted by suit
@@ -37,14 +39,14 @@ class PokerHand
     PokerHand.new(@hand.sort_by { |c| [c.suit, c.face] }.reverse)
   end
 
-  # Returns a new PokerHand object with the cards sorted by value
+  # Returns a new PokerHand object with the cards sorted by face value
   # with the highest value first.
   #
   #     PokerHand.new("3d 5c 8h Ks").by_face.just_cards   # => "Ks 8h 5c 3d"
   def by_face
     PokerHand.new(@hand.sort_by { |c| [c.face, c.suit] }.reverse)
   end
-  
+
   # Returns string representation of the hand without the rank
   #
   #     PokerHand.new(["3c", "Kh"]).just_cards     # => "3c Kh"
@@ -52,7 +54,7 @@ class PokerHand
     @hand.join(" ")
   end
   alias :cards :just_cards
-  
+
   # Returns an array of the card values in the hand.
   # The values returned are 1 less than the value on the card.
   # For example: 2's will be shown as 1.
@@ -94,14 +96,11 @@ class PokerHand
   def four_of_a_kind?
     if (md = (by_face =~ /(.). \1. \1. \1./))
       # get kicker
-      (md.pre_match + md.post_match).match(/(\S)/)
-      [
-        [8, Card::face_value(md[1]), Card::face_value($1)],
-        arrange_hand(md)
-      ]
-    else
-      false
+      result = [8, Card::face_value(md[1])]
+      result << Card::face_value($1) if (md.pre_match + md.post_match).match(/(\S)/)
+      return [result, arrange_hand(md)]
     end
+    false
   end
 
   def full_house?
@@ -164,19 +163,17 @@ class PokerHand
     if (md = (by_face =~ /(.). \1. \1./))
       # get kicker
       arranged_hand = arrange_hand(md)
-      arranged_hand.match(/(?:\S\S ){3}(\S)\S (\S)/)
-      [
-        [
-          4,
-          Card::face_value(md[1]),
-          Card::face_value($1),
-          Card::face_value($2)
-        ],
-        arranged_hand
-      ]
-    else
-      false
+      matches = arranged_hand.match(/(?:\S\S ){2}(\S\S)/)
+      if matches
+        result = [4, Card::face_value(md[1])]
+        matches = arranged_hand.match(/(?:\S\S ){3}(\S)/)
+        result << Card::face_value($1) if matches
+        matches = arranged_hand.match(/(?:\S\S ){3}(\S)\S (\S)/)
+        result << Card::face_value($2) if matches
+        return [result, arranged_hand]
+      end
     end
+    false
   end
 
   def two_pair?
@@ -191,44 +188,52 @@ class PokerHand
       # that were in-between, and the cards that came after.
       arranged_hand = arrange_hand(md[0].sub(md[2], '') + ' ' +
           md.pre_match + ' ' + md[2] + ' ' + md.post_match)
-      arranged_hand.match(/(?:\S\S ){4}(\S)/)
-      [
-        [
-          3,
-          Card::face_value(md[1]),    # face value of the first pair
-          Card::face_value(md[3]),    # face value of the second pair
-          Card::face_value($1)        # face value of the kicker
-        ],
-        arranged_hand
-      ]
-    else
-      false
+      matches = arranged_hand.match(/(?:\S\S ){3}(\S\S)/)
+      if matches
+        result = []
+        result << 3
+        result << Card::face_value(md[1])    # face value of the first pair
+        result << Card::face_value(md[3])    # face value of the second pair
+        matches = arranged_hand.match(/(?:\S\S ){4}(\S)/)
+        result << Card::face_value($1) if matches    # face value of the kicker
+      return [result, arranged_hand]
+      end
     end
+    false
   end
 
   def pair?
     if (md = (by_face =~ /(.). \1./))
-      # get kicker
-      arranged_hand = arrange_hand(md)
-      arranged_hand.match(/(?:\S\S ){2}(\S)\S\s+(\S)\S\s+(\S)/)
-      [
-        [
-          2,
-          Card::face_value(md[1]),
-          Card::face_value($1),
-          Card::face_value($2),
-          Card::face_value($3)
-        ],
-        arranged_hand
-      ]
+      arranged_hand_str = arrange_hand(md)
+      arranged_hand = PokerHand.new(arranged_hand_str)
+
+      if arranged_hand.hand[0].face == arranged_hand.hand[1].face &&
+          arranged_hand.hand[0].suit != arranged_hand.hand[1].suit
+        result = [2, arranged_hand.hand[0].face]
+        result << arranged_hand.hand[2].face if arranged_hand.size > 2
+        result << arranged_hand.hand[3].face if arranged_hand.size > 3
+        result << arranged_hand.hand[4].face if arranged_hand.size > 4
+
+        return [result, arranged_hand_str]
+      end
     else
       false
     end
   end
 
   def highest_card?
-    result = by_face
-    [[1, *result.face_values[0..4]], result.hand.join(' ')]
+    if size > 0
+      result = by_face
+      [[1, *result.face_values[0..result.face_values.length]], result.hand.join(' ')]
+    else
+      false
+    end
+  end
+
+  def empty_hand?
+    if size == 0
+      [[0]]
+    end
   end
 
   OPS = [
@@ -242,6 +247,7 @@ class PokerHand
     ['Two pair',        :two_pair? ],
     ['Pair',            :pair? ],
     ['Highest Card',    :highest_card? ],
+    ['Empty Hand',      :empty_hand? ],
   ]
 
   # Returns the verbose hand rating
@@ -252,18 +258,16 @@ class PokerHand
       (method(op[1]).call()) ? op[0] : false
     }.find { |v| v }
   end
-  
+
   alias :rank :hand_rating
-  
+
   def score
-    # OPS.map returns an array containing the result of calling each OPS method again
-    # the poker hand. The non-nil cell closest to the front of the array represents
+    # OPS.map returns an array containing the result of calling each OPS method against
+    # the poker hand. The truthy cell closest to the front of the array represents
     # the highest ranking.
-    # find([0]) returns [0] instead of nil if the hand does not match any of the rankings
-    # which is not likely to occur since every hand should at least have a highest card
     OPS.map { |op|
       method(op[1]).call()
-    }.find([0]) { |score| score }
+    }.find { |score| score }
   end
 
   # Returns a string of the hand arranged based on its rank. Usually this will be the
@@ -271,11 +275,11 @@ class PokerHand
   #
   #     ph = PokerHand.new("As 3s 5s 2s 4s")
   #     ph.sort_using_rank        # => "5s 4s 3s 2s As"
-  #     ph.by_face.just_cards       # => "As 5s 4s 3s 2s"   
+  #     ph.by_face.just_cards       # => "As 5s 4s 3s 2s"
   def sort_using_rank
     score[1]
   end
-  
+
   # Returns string with a listing of the cards in the hand followed by the hand's rank.
   #
   #     h = PokerHand.new("8c 8s")
@@ -283,20 +287,19 @@ class PokerHand
   def to_s
     just_cards + " (" + hand_rating + ")"
   end
-  
+
   # Returns an array of `Card` objects that make up the `PokerHand`.
   def to_a
     @hand
   end
-  
   alias :to_ary :to_a
-  
+
   def <=> other_hand
     self.score[0].compact <=> other_hand.score[0].compact
   end
-  
+
   # Add a card to the hand
-  # 
+  #
   #     hand = PokerHand.new("5d")
   #     hand << "6s"          # => Add a six of spades to the hand by passing a string
   #     hand << ["7h", "8d"]  # => Add multiple cards to the hand using an array
@@ -304,16 +307,16 @@ class PokerHand
     if new_cards.is_a?(Card) || new_cards.is_a?(String)
       new_cards = [new_cards]
     end
-    
+
     new_cards.each do |nc|
-      unless @@allow_duplicates
+      unless allow_duplicates
         raise "A card with the value #{nc} already exists in this hand. Set PokerHand.allow_duplicates to true if you want to be able to add a card more than once." if self =~ /#{nc}/
       end
-      
+
       @hand << Card.new(nc)
     end
   end
-  
+
   # Remove a card from the hand.
   #
   #     hand = PokerHand.new("5d Jd")
@@ -322,14 +325,14 @@ class PokerHand
   def delete card
     @hand.delete(Card.new(card))
   end
-  
+
   # Same concept as Array#uniq
   def uniq
     PokerHand.new(@hand.uniq)
   end
-  
+
   # Resolving methods are just passed directly down to the @hand array
-  RESOLVING_METHODS = [:size, :+, :-]
+  RESOLVING_METHODS = [:each, :size, :-]
   RESOLVING_METHODS.each do |method|
     class_eval %{
       def #{method}(*args, &block)
@@ -337,20 +340,106 @@ class PokerHand
       end
     }
   end
-  
+
+  def allow_duplicates
+    @@allow_duplicates
+  end
+
+  # Checks whether the hand matches usual expressions like AA, AK, AJ+, 66+, AQs, AQo...
+  #
+  # Valid expressions:
+  # * "AJ": Matches exact faces (in this case an Ace and a Jack), suited or not
+  # * "AJs": Same but suited only
+  # * "AJo": Same but offsuit only
+  # * "AJ+": Matches an Ace with any card >= Jack, suited or not
+  # * "AJs+": Same but suited only
+  # * "AJo+": Same but offsuit only
+  # * "JJ+": Matches any pair >= "JJ".
+  # * "8T+": Matches connectors (in this case with 1 gap : 8T, 9J, TQ, JK, QA)
+  # * "8Ts+": Same but suited only
+  # * "8To+": Same but offsuit only
+  #
+  # The order of the cards in the expression is important (8T+ is not the same as T8+), but the order of the cards in the hand is not ("AK" will match "Ad Kc" and "Kc Ad").
+  #
+  # The expression can be an array of expressions. In this case the method returns true if any expression matches.
+  #
+  # This method only works on hands with 2 cards.
+  #
+  #     PokerHand.new('Ah Ad').match? 'AA' # => true
+  #     PokerHand.new('Ah Kd').match? 'AQ+' # => true
+  #     PokerHand.new('Jc Qc').match? '89s+' # => true
+  #     PokerHand.new('Ah Jd').match? %w( 22+ A6s+ AJ+ ) # => true
+  #     PokerHand.new('Ah Td').match? %w( 22+ A6s+ AJ+ ) # => false
+  #
+  def match? expression
+    raise "Hands with #{@hand.size} cards is not supported" unless @hand.size == 2
+
+    if expression.is_a? Array
+      return expression.any? { |e| match?(e) }
+    end
+
+    faces = @hand.map { |card| card.face }.sort.reverse
+    suited = @hand.map { |card| card.suit }.uniq.size == 1
+    if expression =~ /^(.)(.)(s|o|)(\+|)$/
+      face1 = Card.face_value($1)
+      face2 = Card.face_value($2)
+      raise ArgumentError, "Invalid expression: #{expression.inspect}" unless face1 and face2
+      suit_match = $3
+      plus = ($4 != "")
+
+      if plus
+        if face1 == face2
+          face_match = (faces.first == faces.last and faces.first >= face1)
+        elsif face1 > face2
+          face_match = (faces.first == face1 and faces.last >= face2)
+        else
+          face_match = ((faces.first - faces.last) == (face2 - face1) and faces.last >= face1)
+        end
+      else
+        expression_faces = [face1, face2].sort.reverse
+        face_match = (expression_faces == faces)
+      end
+      case suit_match
+      when ''
+        face_match
+      when 's'
+        face_match and suited
+      when 'o'
+        face_match and !suited
+      end
+    else
+      raise ArgumentError, "Invalid expression: #{expression.inspect}"
+    end
+  end
+
+  def +(other)
+    cards = @hand.map { |card| Card.new(card) }
+    case other
+    when String
+      cards << Card.new(other)
+    when Card
+      cards << other
+    when PokerHand
+      cards += other.hand
+    else
+      raise ArgumentError, "Invalid argument: #{other.inspect}"
+    end
+    PokerHand.new(cards)
+  end
+
   private
-  
+
   def check_for_duplicates
-    if @hand.size != @hand.uniq.size && !@@allow_duplicates
+    if @hand.size != @hand.uniq.size && !allow_duplicates
       raise "Attempting to create a hand that contains duplicate cards. Set PokerHand.allow_duplicates to true if you do not want to ignore this error."
     end
   end
-  
+
   # if md is a string, arrange_hand will remove extra white space
   # if md is a MatchData, arrange_hand returns the matched segment
   # followed by the pre_match and the post_match
   def arrange_hand(md)
-      hand = if (md.respond_to?(:to_str))
+      hand = if md.respond_to?(:to_str)
         md
       else
         md[0] + ' ' + md.pre_match + md.post_match
@@ -358,12 +447,23 @@ class PokerHand
       hand.strip.squeeze(" ")   # remove extra whitespace
   end
 
-  # delta transform creates a version of the cards where the delta
-  # between card values is in the string, so a regexp can then match a
-  # straight and/or straight flush
+  # delta transform returns a string representation of the cards where the
+  # delta between card values is in the string. This is necessary so a regexp
+  # can then match a straight and/or straight flush
+  #
+  # Examples
+  #
+  #   PokerHand.new("As Qc Jh Ts 9d 8h")
+  #   # => '0As 2Qc 1Jh 1Ts 19d 18h'
+  #
+  #   PokerHand.new("Ah Qd Td 5d 4d")
+  #   # => '0Ah 2Qd 2Td 55d 14d'
+  #
   def delta_transform(use_suit = false)
+    # In order to check for both ace high and ace low straights we create low
+    # ace duplicates of all of the high aces.
     aces = @hand.select { |c| c.face == Card::face_value('A') }
-    aces.map! { |c| Card.new(1,c.suit) }
+    aces.map! { |c| Card.new(0, c.suit) }  # hack to give the appearance of a low ace
 
     base = if (use_suit)
       (@hand + aces).sort_by { |c| [c.suit, c.face] }.reverse
@@ -371,6 +471,7 @@ class PokerHand
       (@hand + aces).sort_by { |c| [c.face, c.suit] }.reverse
     end
 
+    # Insert delta in front of each card
     result = base.inject(['',nil]) do |(delta_hand, prev_card), card|
       if (prev_card)
         delta = prev_card - card.face
@@ -403,5 +504,5 @@ class PokerHand
     # careful to use gsub as gsub! can return nil here
     arranged_hand.gsub(/\s+$/, '')
   end
-  
-end
+
+end