/ 
Game-Cribbage-0.14
/ Game::Cribbage::Player::Hand

NAME

Game::Cribbage::Player::Hand - a player's hand of cards within a hands cycle

VERSION

Version 0.12

SYNOPSIS

use Game::Cribbage::Player::Hand;
use Game::Cribbage::Deck::Card;

my $hand = Game::Cribbage::Player::Hand->new(player => 'player1');

$hand->add(Game::Cribbage::Deck::Card->new(suit => 'H', symbol => 'K'));

my $card = $hand->get(0);
my $card = $hand->get($other_card);  # match by card object

$hand->discard(0, $crib_hand);

my $score = $hand->calculate_score();

PROPERTIES

id

Read/write integer property for a database or external identifier.

$hand->id;
$hand->id($id);

player

Read/write string or object property identifying which player owns this hand (e.g. 'player1').

$hand->player;

score

Read/write object property holding the Game::Cribbage::Score result for the main hand, populated by calculate_score.

$hand->score;

crib_score

Read/write object property holding the Game::Cribbage::Score result for the crib cards, populated by calculate_score when crib cards are present.

$hand->crib_score;

starter

Read/write object property holding the starter Game::Cribbage::Deck::Card, used when scoring the hand.

$hand->starter;
$hand->starter($card);

cards

Read/write arrayref of Game::Cribbage::Deck::Card objects forming the player's main hand.

$hand->cards;

crib

Read/write arrayref of Game::Cribbage::Deck::Card objects in the crib (cards discarded by this player or assigned to them as crib holder).

$hand->crib;

play_scored

Read/write arrayref of Game::Cribbage::Play::Score objects recording points earned during the play phase.

$hand->play_scored;

FUNCTIONS

get

Returns the card at position $card_index in cards when given an integer, or performs a match lookup when given a card object. Dies with 'NO CARD FOUND' if no matching card exists.

my $card = $hand->get(0);
my $card = $hand->get($other_card);

match

Searches cards for a card matching $card (by suit and symbol) and returns it, or returns 0 if not found.

my $found = $hand->match($card);

add

Appends $card to the cards arrayref.

$hand->add($card);

add_by_index

Places $card at the specified index in cards, replacing whatever was there.

$hand->add_by_index(2, $card);

discard_cards

Discards all cards in $cards (arrayref of card objects to identify by suit/symbol) from this hand into $crib hand's crib. Dies with 'CANNOT DISCARD' if the hand has four or fewer cards. Returns an arrayref of the discarded cards.

my $discarded = $hand->discard_cards(\@cards, $crib_hand);

discard

Discards a single card (by index or card object) from this hand into $crib hand's crib. Dies with 'CANNOT DISCARD' if the hand has four or fewer cards.

$hand->discard(0, $crib_hand);
$hand->discard($card, $crib_hand);

add_crib_card

Appends $card to the crib arrayref.

$hand->add_crib_card($card);

calculate_score

Scores the main hand (and crib if present) using Game::Cribbage::Score, setting score and optionally crib_score. Returns the combined numeric score.

my $total = $hand->calculate_score();

card_exists

Returns 1 if $card is found in either cards or crib; otherwise 0.

$hand->card_exists($card);

identify_worst_cards

Finds the best 4-card subset of the 6-card hand by brute-force combination scoring, then returns a list (\@worst_cards, @worst_indexes) identifying the two cards to discard. Dies if the hand does not have exactly 6 cards.

my ($cards, @indexes) = $hand->identify_worst_cards();

validate_crib_cards

Checks that all cards in $cards exist in the current crib. If not, replaces the entire crib with the supplied cards. Always returns 1.

$hand->validate_crib_cards(\@cards);

best_run_play

Selects the best card to play from the unused cards in this hand, preferring cards that score points. Returns the chosen Game::Cribbage::Deck::Card, or a Game::Cribbage::Error with go set when no valid card remains.

my $card = $hand->best_run_play($play);

AUTHOR

LNATION, <email at lnation.org>

BUGS

Please report any bugs or feature requests to bug-game-cribbage at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Game-Cribbage. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Game::Cribbage

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2024 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)