43KNlxM - Games::Cards::Poker.pm created by Pip Stuart <[email protected]> to provide
  Poker functions (&& maybe later objects) using only Perl.

NAME

Games::Cards::Poker - Pure Perl Poker functions

VERSION

This documentation refers to version 1.0.44P0KER of
Games::Cards::Poker, which was released on Sun Apr 25 00:20:14:27 2004.

SYNOPSIS

 use Games::Cards::Poker;

 # Deal 4 players hands && score them...
 my $players   = 4; # number of players to get hands dealt
 my $hand_size = 5; # number of cards to deal to each player
 my @hands     = ();# player hand data
 my @deck      = Shuffle(Deck());
 while($players--) {
   foreach(1..$hand_size) {
     push(@{$hands[$players]}, pop(@deck));
   }
   printf("Player%d score:%4d hand:@{$hands[$players]}\n",
     $players, ScoreHand(@{$hands[$players]}));
 }

DESCRIPTION

Poker provides a few simple functions for creating
decks of cards && manipulating them for simple Poker games
or simulations.

2DO

- mk Games::Cards compatability object interface

- better error checking

-    What else does Poker need?

USAGE

Deck()

Returns a new array of scalars with the abbreviated Poker names of
cards (eg. 'As' for 'Ace of Spades', 'Td' for 'Ten of Diamonds',
'2c' for 'Two of Clubs', etc.).

Use CardName() to expand abbreviated cards into their full names.

Shuffle(@cards)

Shuffles the passed in @cards array in one quick pass.  Shuffle()
returns a shuffled copy of the @cards array.

Shuffle() can also take an arrayref parameter instead of an explicit
@cards array in which case, the passed in arrayref will be shuffled
in place && the return value need not be reassigned.

SortCards(@cards)

Sorts the passed in @cards array.  SortCards() returns a sorted copy
of the @cards array.

SortCards() can also take an arrayref parameter instead of an explicit
@cards array in which case, the passed in arrayref will be sorted
in place && the return value need not be reassigned.

SortCards() works consistently on the return values of ShortHand()
as well as abbreviated cards (eg. 'AAA', 'AAK'..'AKQs', 'AKQ'..'222').

ShortHand(@hand)

Returns a scalar string containing the abbreviated Poker description
of @hand (eg. 'AKQJTs' eq 'Royal Flush', 'QQ993' eq 'Two Pair', etc.).

ShortHand() calls SortCards() on it's parameter before doing the
abbreviation to make sure that the return value is consistent.

ShortHand() can be called on fewer cards than a full @hand of 5 to
obtain other useful abbreviations (eg. ShortHand(@hole) will return
the abbreviated form of a player's two hole [pocket] cards or
ShortHand(@flop) will abbreviate the three community cards which
flop onto the board in Texas Hold'Em).

SlowScoreHand(@hand)

Returns an integer score (where lower is better) for the passed in
Poker @hand.  This means 0 (zero) is returned for a Royal Flush &&
the worst possible score is 7461 awarded to 7, 5, 4, 3, 2 unsuited.

If you want higher scores to mean higher hands, just subtract the
return value from 7461.

All suits are considered to have equal value in this scoring function.
It should be easy to use ScoreHand() as a first pass where ties can
be resolved by another suit-comparison function if you want such
behavior.

HandScore($score)

This function is the opposite of ScoreHand().  It takes an integer
$score parameter && returns the corresponding ShortHand string.

HandScore() uses a fully enumerated table to just index the
associated ShortHand so it should be quite fast.  The table was
generated using SlowScoreHand().

ScoreHand(@hand)

This is a new version of SlowScoreHand() which does the opposite of
HandScore() by indexing a ShortHand() key string into a hash of
corresponding score values.  This faster version should be used for
any normal hand scoring needs.  If you still want to use the slower
version, you can call the UseSlow() function to make ScoreHand()
actually call SlowScoreHand() instead of just indexing the answer
score in a hash.

UseSlow([$slow])

UseSlow() is a function provided in case you'd prefer to actually
employ the SlowScoreHand() function whenever you call ScoreHand().

UseSlow() takes an optional $slow value.  If you don't
provide $slow, UseSlow() will toggle the slow state.

UseSlow() always returns the current state of whether
SlowScoreHand() is being used whenever ScoreHand() is called.

BestIndices(@cards)

BestIndices() takes 5 or more cards (normally 7) which can be
split among separate arrays (like BestIndices(@hole, @board) for
Hold'Em) && returns an array of the indices of the 5 cards (hand)
which yield the best score.

BestHand(@best, @cards)

BestHand() takes the return value of BestIndices() as the
first parameter (which is an array of the best indices) && then the
same other parameters (@cards) or (@hole, @board) to give you a copy
of just the best cards.  The return value of this function can be
passed to ScoreHand() to get the score of the best hand.

BestHand() can optionally take just the @cards like
BestIndices() && it will automagically call BestIndices()
first to obtain @best.  It will then return copies of those indexed
cards from the @cards.

CardName($card)

CardName() takes an abbreviated card (eg. 'As', 'Kh', '2c') &&
returns the expanded full name of the card ('Ace of Spades',
'King of Hearts', 'Two of Clubs').

NameCard($name)

NameCard() does the opposite of CardName() by taking an expanded
full name (eg. 'Queen of Diamonds', 'Jack of Hearts', 'Ten of Clubs')
&& returns the abbreviated card (eg. 'Qd', 'Jh', 'Tc').

HandName($score)

HandName() takes a HandScore() parameter && returns the name of
the corresponding scoring category it falls under (eg. 'Royal Flush',
'Three-of-a-Kind', 'High Card').

HandName() can optionally accept an arrayref to a hand, the @hand
itself, or a ShortHand instead of the $score parameter to find out
the HandName of any of those.

WHY?

Games::Poker::* wouldn't compile correctly for me so I thought it
 shouldn't take too long to write my own. =)  It was a fun problem...
 much trickier than I first imagined but I think I have solved the
 problem elegantly once && for all.

NOTES

Suits are: s,h,d,c (Spade,Heart,Diamond,Club) like bridge (alphabetical).
 Although they are sorted && appear in this order, suits are ignored for
 scoring by default (but can be optionally reordered && scored later)

B64 notes: Cards map perfectly into A..Z,a..z so += 10 for only letter rep

B64 Cards: 0.As 4.Ks 8.Qs C.Js G.Ts K.9s O.8s S.7s W.6s a.5s e.4s i.3s m.2s
           1.Ah 5.Kh 9.Qh D.Jh H.Th L.9h P.8h T.7h X.6h b.5h f.4h j.3h n.2h
           2.Ad 6.Kd A.Qd E.Jd I.Td M.9d Q.8d U.7d Y.6d c.5d g.4d k.3d o.2d
           3.Ac 7.Kc B.Qc F.Jc J.Tc N.9c R.8c V.7c Z.6c d.5c h.4c l.3c p.2c
    Ranks:   0    1    2    3    4    5    6    7    8    9    A    B    C
B64 Cards: 0.As   1.Ah   2.Ad   3.Ac        Ranks: 0
           4.Ks   5.Kh   6.Kd   7.Kc               1
           8.Qs   9.Qh   A.Qd   B.Qc               2
           C.Js   D.Jh   E.Jd   F.Jc               3
           G.Ts   H.Th   I.Td   J.Tc               4
           K.9s   L.9h   M.9d   N.9c               5
           O.8s   P.8h   Q.8d   R.8c               6
           S.7s   T.7h   U.7d   V.7c               7
           W.6s   X.6h   Y.6d   Z.6c               8
           a.5s   b.5h   c.5d   d.5c               9
           e.4s   f.4h   g.4d   h.4c               A
           i.3s   j.3h   k.3d   l.3c               B
           m.2s   n.2h   o.2d   p.2c               C
           q.Jok0 r.Jok1                          -1

Error checking is minimal.

I hope you find Games::Cards::Poker useful.  Please feel free to e-mail
me any suggestions or coding tips or notes of appreciation
("app-ree-see-ay-shun").  Thank you.  TTFN.

CHANGES

Revision history for Perl extension Games::Cards::Poker:

- 1.0.44P0KER  Sun Apr 25 00:20:14:27 2004

* made CardName() to return 'Ace of Spades' or 'Two of Clubs' for
         'As'or'A' or '2c'or'z' && NameCard() to do inverse

* made HandName() to return 'Royal Flush' or 'High Card' for
         ScoreHand() or ShortHand() or @hand or \@hand && NameHand()

* rewrote SortCards() to accept any length ShortHand() params

* s/valu/rank/g s/scor/score/g s/bord/board/g

- 1.0.44LCEw8  Wed Apr 21 12:14:58:08 2004

* s/HoldEm//g; on advice from Joe since Best*() are useful for more
   than just Hold'Em (like 7-card stud)

* fixed minor typos in POD

- 1.0.44KFNKP  Tue Apr 20 15:23:20:25 2004

* wrote UseSlow() so that benchmrk.pl would still work without Best()
   && in case anyone would rather have ScoreHand() call
   SlowScoreHand() every time instead.

* since my old Best() was actually slower than BestHoldEmIndices() =O
   I removed Best().

* since old Scor() was so much faster than old ScoreHand(), I renamed
   them to ScoreHand() && SlowScoreHand() respectively since
   computational version is unnecessary now.

* wrote benchmrk.pl to test BestHoldEmIndices() + ScoreHand() against
   Best() + Scor().  Best()+Scor() only took 60% as long to run.

* added SortCards() call on ShortHand() param just in case

- 1.0.44ILBKV  Sun Apr 18 21:11:20:31 2004

* wrote Scor() with gen'd enumerated hash of ShortHand => Score

* wrote HandScore() to just lookup index of a ShortHand from a score

* squashed 4 scoring bugs in one pair section

* used Algorithm::ChooseSubsets for new BestHoldEmIndices
   (on Jan's recommendation)

* renamed enumerated BestHoldEmIndices() as Best()

* gave ScoreHand() optional arrayref param like others

* gave ScoreHand() optional ShortHand() string param

* updated 2do && tidied up documentation a bit

- 1.0.44H2DUS  Sat Apr 17 02:13:30:28 2004

* added BestHoldEmIndices() && BestHoldEmHand() for Tim && Jan

* commented unnecessary Games::Cards inheritance since I haven't written
any compatability / object interface yet

- 1.0.44F2Q8F  Thu Apr 15 02:26:08:15 2004

* original version

INSTALL

Please run:

   `perl -MCPAN -e "install Games::Cards::Poker"`

or uncompress the package and run the standard:

   `perl Makefile.PL; make; make test; make install`

LICENSE

Most source code should be Free!
 Code I have lawful authority over is and shall be!
Copyright: (c) 2004, Pip Stuart.  All rights reserved.
Copyleft :  I license this software under the GNU General Public
 License (version 2).  Please consult the Free Software Foundation
 (http://www.fsf.org) for important information about your freedom.

AUTHOR

Pip Stuart <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.