NAME

Games::Cards -- Perl module for playing card games

SYNOPSIS

    use Games::Cards;

    my $Rummy = new Games::Cards::Game;

    # Create and shuffle the deck
    my $Deck = $Rummy->create_deck;
    $Deck->shuffle;

    # Deal out the hands
    foreach my $i (1 .. 3) {
	my $hand = new Games::Cards::Stack "Player $i" ;
	$Deck->give_cards($hand, 7);
	push @Hands, $hand;
    }

    # print hands (e.g. "Player 1: KD QD JD 1S 2C 3C 3H")
    foreach (@Hands) { print $_->print("short") }

    # Initialize the undo engine to save 100 moves
    Games::Cards::Undo->initialize(100);
    Games::Cards::Undo->undo; # undo last move
    Games::Cards::Undo->un_undo; # redo last undone move

DESCRIPTION

This module creates objects to allow easier programming of card games.

Class Games::Cards::Game

This class represents a certain game, like War, or Solitaire. This is necessary to store the various rules for a given game, like the ranking of the cards. (Or, for more exotic games, how many cards of what type are in the deck.) Methods:

new(HASHREF)

creates a new game. HASHREF is a reference to a hash containing zero or more of the keys "suits" and "cards_in_suit". "suits" is a list of the suits in a deck, "cards_in_suit" is a reference to a hash whose keys are the names of the cards in one suit and whose values are the values (or ranks) of those cards. If "suits" is not given, the default suits (Clubs, Diamonds, Hearts, Spades) are used. If "cards_in_suit" is not given, the default cards (Ace, 2..10, Jack, Queen, King with values 1..13) are used. For example, war would require "Ace"=>14.

create_deck

creates an unshuffled deck of cards. For each card in the deck it creates a name, suit, and value. The deck was stipulated by the 'new Games::Cards' command. Returns the deck.

Class Games::Cards::Queue

A queue (cf. computer science terminology, or the C++ stdlib) is a first-in first-out pile of cards. Cards are removed from the top of the pile, but new cards are added to the bottom of the pile. This might represent, say, a pile of face-down cards, like the player's hand in War.

Class Games::Cards::Stack

A stack (cf. computer science terminology, or the C++ stdlib) is a last-in first-out pile of cards. Cards are removed from the top of the pile, and new cards are also added to the top of the pile. This would usually represent a pile of cards with its top card (and perhaps all cards) face up.

Class Games::Cards::CardSet

A CardSet is just an array of cards (stored in the "cards" field). It could be a player's hand, a deck, or a discard pile, for instance. This is a super class of Queue and Stack, and those classes should be used instead, so that we know whether the cards in the pile are FIFO or LIFO. Methods:

shuffle

shuffles the cards in the CardSet

give_cards(RECEIVER, NUMBER)

Transfers NUMBER cards from the donor (the object on which this method was called) to the CardSet RECEIVER. This method can used for dealing cards from a deck, giving cards to another player (Go Fish), putting cards on the table (War), or transferring a card or cards between piles in solitaire.

If NUMBER is "all", then the donor gives all of its cards.

Returns 1 usually. If the donor has too few cards, it returns 0 and does not transfer any cards.

top_card

Returns the top Card in the CardSet (or 0 if CardSet is empty)

face_down

Makes a whole CardSet face down

face_up

Makes a whole CardSet face up

print(LENGTH)

Returns a string containing a printout of the Cards in the CardSet. Prints a long printout if LENGTH is "long", short if "short" (or nothing). The CardSet is printed out so that the top card of the set is printed first.

name

Returns the name of the Set

cards

Returns a reference to the array of Cards in the set

size

Tells how many cards are in the set

Class Games::Cards::Card

A Card is a playing card. Methods:

new(HASHREF)

creates a new card. HASHREF references a hash with keys "suit" and "name".

print(LENGTH)

returns a string with the whole card name ("King of Hearts") if LENGTH is "long", otherwise a short version ("KH").

name(LENGTH)

prints the name of the card. The full name if LENGTH is "long"; otherwise a short version ("K");

suit(LENGTH)

Returns the suit of the card. Returns the long version ("Diamonds") if LENGTH is "long", else a short version ("D").

color

Is the card "red" or "black"? Returns the color or undef for unknown color.

value

Calculates the value of a card

is_face_up

Returns true if a card is face up

is_face_down

Returns true if a card is face down

face_up

Makes a card face up

face_down

Makes a card face down

Class Games::Cards::Undo

This is the package for methods to undo & redo moves. There is no CG::Undo object. But there is a (private) array of the preceding moves (private CG::Undo::Move objects). Methods:

initialize(MOVES)

Initialize the Undo engine. MOVES is the number of moves to save. 0 (or no argument) allows infinite undo. This method must be called before any undo-able moves are made (i.e., it can be called after the hands are dealt). This method will also re-initialize the engine for a new game.

undo

Undo a move

un_undo

Redo a move that had been undone with undo. (un_undo instead of redo, because redo is a reserved word.)

EXAMPLES

An implementation of Klondike (aka standard solitaire) demonstrates how to use this module in a simple game.

NOTES

TODO

• method to arrange a set, e.g. sort it by suit and value within the suit.

• give_cards method that gives specific card(s) rather than the top card(s) in the set. Or cards that match a certain criterion (e.g. all 8's). Or a part of a column in solitaire (all cards from a certain card to the top)

Maybe TODO

• Hand class that doesn't care about FIFO? I.e. it's not a Stack or a Queue because there's no concept of the top card. You're only allowed to use the fancier give_cards method, where you list specific cards to give.

• Make various classes and methods private

• Clone/deep copy method for a CardSet. This would allow e.g. saving a deck to restart the same game of solitaire.

• Move Undo to Undo.pm? Use EXPORT in that file for undo & un_undo? (Or is "undo" going to clobber another undo method? (call it undo_move?))

Not TODO

Computer AI and GUI display are left as exercises for the reader.

BUGS

Probably. This is pre-alpha.

AUTHOR

Amir Karger, karger@post.harvard.edu

SEE ALSO

perl(1).

cpanm Games::Cards

perl -MCPAN -e shell
install Games::Cards