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:
This package handles undoing and redoing moves (important for solitaire).
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:
Returns the current Game object. In almost every case, you'll only be working with one at a time.
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.
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.
Returns the CardSet with name NAME
Returns the CardSet with nickname NAME
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.
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 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.
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.
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:
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.
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:
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.
Rearrange a Hand by putting Card described by DESCRIPTION at index INDEX.
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.
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.
shuffles the cards in the CardSet. Shuffling is not undoable.
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.
Sorts the Set by suit, but not by value within the suit.
Sorts the Set by suit, then by value within the suit.
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.
Makes a whole CardSet face down
Makes a whole CardSet face up
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.
Returns the name of the Set
Returns the nickname of the Set (or undef if there is none)
Returns a reference to the array of Cards in the set
Tells how many cards are in the set
A Card is a playing card. Methods:
creates a new card. GAME is the Game this card is being created in. HASHREF references a hash with keys "suit" and "name".
makes a copy of the Card (not just a reference to it).
returns a string with the whole card name ("King of Hearts") if LENGTH is "long", otherwise a short version ("KH").
Gives a unique description of this card, i.e., you're guaranteed that no other card in the Game will have the same description.
prints the name of the card. The full name ("King") if LENGTH is "long"; otherwise a short version ("K");
Returns the suit of the card. Returns the long version ("Diamonds") if LENGTH is "long", else a short version ("D").
Is the card "red" or "black"? Returns the color or undef for unknown color.
Calculates the value of a card
Returns the suit_value of a card (1..number of suits)
Returns true if a card is face up
Returns true if a card is face down
Makes a card face up
Makes a card face down
Returns the CardSet which this Card is a part of
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.
Laziness applies in Games::Cards just like in the rest of Perl. It will be much easier if you start with an existing game.
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.
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)
3 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
To install Games::Cards, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Games::Cards
CPAN shell
perl -MCPAN -e shell install Games::Cards
For more information on module installation, please visit the detailed CPAN module installation guide.