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

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

    # Create the correct deck for a game of Rummy.
    my $Deck = new Games::Cards::Deck ($Rummy, "Deck");

    # shuffle the deck and create the discard pile
    $Deck->shuffle;
    my $Discard = new Games::Cards::Queue "Discard Pile";

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

    # print hands (e.g. "Player 1: AS  2C  3C  3H 10D  QS  KH")
    foreach (@Hands) { print ($_->print("short"), "\n") }

    $Hands[1]->give_a_card ($Discard, "8D"); # discard 8 of diamonds

This module creates objects and methods to allow easier programming of card games in Perl. It allows you to do things like create decks of cards, have piles of cards, hands, and other sets of cards, turn cards face-up or face-down, and move cards from one set to another. Which is pretty much all you need for most card games.

Sub-packages include:

Games::Cards::Undo

This package handles undoing and redoing moves (important for solitaire).

and Games::Cards::Tk

This package allows you to write games that use a Tk graphical interface. It's designed so that it will be relatively easy to write a game that uses i<either> a GUI or a simple text interface, depending on the player's circumstances (availability of Tk, suspicious boss, etc.). See Games::Cards::Tk for more details on writing Tk games.

A GC::Game stores information like what cards are in the starting deck, plus pointers to the various Cards and CardSets.

A GC::Card represents one playing card. Every Card must belong to one (and only one) CardSet at every point during the game.

A GC::CardSet is mostly just a set of GC::Cards. A CardSet has a unique name. Many also have short nicknames, which make it easier to write games that move cards between the sets. (See Klondike or FreeCell, for example.)

There are many sorts of CardSet. The basic differentiation is Piles, for which you only access the top or bottom card (or cards) and Hands, where you might access any one of the cards in the Hand. Piles are broken up into Stacks and Queues, and every game starts with a Deck of cards (or more than one).

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:

current_game

Returns the current Game object. In almost every case, you'll only be working with one at a time.

set_current_game(GAME)

In theory, these subs let you handle multiple Games at once, as long as you set_current_game to the right one. Note that Game->new automatically sets the current Game to be that game, so in 99% of cases, you won't have to call set_current_game.

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.

get_cardset_by_name(N)

Returns the CardSet with name NAME

get_cardset_by_nickname(N)

Returns the CardSet with nickname NAME

get_card_by_truename(N)

Returns the Card with truename NAME

A deck is a deck of cards. The number of cards and identities of the cards in the deck depend on the particular Game for which the deck is used.

new (GAME, NAME)

creates an unshuffled deck of cards. For each card in the deck it creates a name, suit, value, and suit value. GAME is the GC::Game this deck belongs to, and it stipulates the number of cards in the deck, etc. NAME is the name to give the deck, e.g. Deck.

A Queue (cf. computer science terminology, or the 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.

A stack (cf. computer science terminology, or the 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.

A Pile is a pile of cards. That is, it is a CardSet where we will only access the beginning or end of the set. (This may include the first N cards in the set, but we will never reference the 17'th card.) 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:

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)

A Hand represents a player's hand. Most significantly, it's a CardSet which is different from a Pile because the Cards in it are unordered. We may reference any part of the CardSet, not just the top or bottom. Methods:

give_a_card(RECEIVER, DESCRIPTION)

Transfers Card described by DESCRIPTION from the donor (the Hand on which this method was called) to the CardSet RECEIVER. This method can used for discarding a card from a hand, e.g. If DESCRIPTION matches /^-?\d+$/, then it is the index in the cards array of the Card to give. Otherwise, DESCRIPTION is passed to Hand::index. Returns 1 usually. If the donor does not have the card, it returns 0 and does not transfer anything.

move_card(DESCRIPTION, INDEX)

Rearrange a Hand by putting Card described by DESCRIPTION at index INDEX. If DESCRIPTION matches /^-?\d+$/, then it is the index in the cards array of the Card to give. Otherwise, DESCRIPTION is passed to Hand::index. Returns 1 usually. If the donor does not have the card, it returns 0 and does not transfer anything.

index(DESCRIPTION)

Given a card description DESCRIPTION return the index of that Card in the Hand, or undef if it was not found. DESCRIPTION may be a Card or a string (like 8H or KC).

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 a number of other classes, and those subclasses should be used instead.

new(GAME, NAME, NICKNAME)

create a new (empty) CardSet. GAME is the Game object that this set belongs to. NAME is a unique string that e.g. can be output when you print the CardSet. Optionally, NICKNAME is a (unique!) short name that will be used to reference the set.

shuffle

shuffles the cards in the CardSet. Shuffling is not undoable.

sort_by_value

Sorts the Set by value. This and other sort routines will probably be used mostly on Hands, which are ordered sets, but you might want to reorder a deck or something. Sorting is not undoable.

sort_by_suit

Sorts the Set by suit, but not by value within the suit.

sort_by_suit_and_value

Sorts the Set by suit, then by value within the suit.

clone(GAME, NAME, NICKNAME)

Create a copy of this CardSet. That is, create an object with the same class as arg0. Then make a copy of each Card in the CardSet (true copy, not a reference). arg1 is the Game that the set belongs to. arg2 is the name to give the new CardSet. arg3 (optional) is the nickname.

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 in reverse order, so that the top card of the set is printed first.

name

Returns the name of the Set

nickname

Returns the nickname of the Set (or undef if there is none)

cards

Returns a reference to the array of Cards in the set

size

Tells how many cards are in the set

A Card is a playing card. Methods:

new(GAME, HASHREF)

creates a new card. GAME is the Game this card is being created in. HASHREF references a hash with keys suit and name.

clone(GAME)

makes a copy of the Card (not just a reference to it).

print(LENGTH)

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

truename

Gives a unique description of this card, i.e., you're guaranteed that no other card in the Game will have the same description.

name(LENGTH)

prints the name of the card. The full name (King) 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

suit_value

Returns the suit_value of a card (1..number of suits)

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

owning_cardset

Returns the CardSet which this Card is a part of

set_owning_cardset(SET_OR_NAME)

Makes the Card a part of a CardSet. Arg0 is either an actual CardSet ref, or the name of a CardSet.

An implementation of Klondike (aka standard solitaire) demonstrates how to use this module in a simple game. Other card game examples are included as well. The Games::Cards README should list them all.

So you want to write a card game using Games::Cards (or even Games::Cards::Tk)? Great! That's what the module is for. Here are some tips about how to write a game.

Steal code

Laziness applies in Games::Cards just like in the rest of Perl. It will be much easier if you start with an existing game.

Stack vs. Queue

Think carefully about whether the Piles in your game are Stacks (LIFO) or Queues (FIFO). As a general rule, piles of cards that are usually face down will be Stacks; face up will be Queues. CardSets where you want to access specific cards (i.e., not just the first or last) will be Hands.

GUI games

I've tried to design Games::Cards::Tk and the games that use it so that the Tk game is very similar to the text game. This allows the most code reuse. GUI games may involve clicking, dragging, and a different way to display the game; but the underlying game is still the same. Also note that serious timewasters may prefer to use the keyboard to play GUI games. See Games::Cards::Tk for more details.

This module contains a bunch of methods. The public methods are documented here. That means any method not documented here is probably private, which means you shouldn't call it directly. There are also a bunch of classes. Most private classes are not documented here. A couple private classes are mentioned, since they have methods which public classes inherit. In that case, the privateness is mentioned.

See the TODO file in the distribution

Computer AI and GUI display were left as exercises for the reader. Then Michael Houghton wrote a Tk card game, so I guess the readers are doing their exercises.

You betcha. It's still alpha. test.pl doesn't work with MacPerl, because it uses backticks. However, (as far as I know) the games released with Games::Cards do work.

Amir Karger Andy Bach wrote a Free Cell port, and gets points for the first submitted game, plus some neat ideas like CardSet::clone. Michael Houghton herveus@Radix.Net wrote the initial Tk Free Cell (two days after Andy submitted his Free Cell!) I changed almost all of the code eventually, to fit in with Games::Cards::Tk, but he gave me the initial push (and code to steal).

Copyright (c) 1999-2000 Amir Karger

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

perl(1), Tk(1)