package Games::Sequential::Position;
use strict;
use warnings;

use Carp;
use Storable qw(dclone);
use 5.006001;

our $VERSION = '0.3.1';

=head1 NAME

Games::Sequential::Position - base Position class for use with Games::Sequential 

=head1 SYNOPSIS

    package My::GamePos;
    use base Games::Sequential::Position;

    sub init { ... }   # setup initial state
    sub apply { ... }

    package main;
    my $pos = My::GamePos->new;
    my $game = Games::Sequential->new($pos);


=head1 DESCRIPTION

Games::Sequential::Position is a base class for position-classes
that can be used with L<Games::Sequential>. This class is
provided for convenience; you don't need this class to use
C<Games::Sequential>. It is also possible to use this class on
its own.

=head1 PURE VIRTUAL METHODS

Modules inheriting this class must implement at least the
C<apply()> method. If you chose to not use this class, you must
also implement a C<copy()> method which makes a deep copy of the
object.

=over 4

=item apply($move)

Accept a move and apply it to the current state producing the
next state. Return a reference to itself. Note that this method
is responsible for also advancing the state's perception of which
player's turn it is.

Something like this (sans error checking):

    sub apply {
        my ($self, $move) = @_;

        ... apply $move, creating next position ...

        return $self;
    }

=cut

sub apply {
    croak "apply(): Call to pure virtual method\n";
}

=back

=head1 METHODS

The following methods are provided by this class.

=over 4

=item new [@list]

Create and return an object. Any arguments is passed on to the
C<init()> method. Return a blessed hash reference.

=cut 

sub new {
    my $invocant = shift;
    my $class = ref($invocant) || $invocant;
    my $self = bless {}, $class;

    $self->init(@_) or carp "Failed to initialise object!";

    return $self;
}


=item init [@list]

Initialize an object. By default, this only means setting player
1 to be the current player.

This method is called by C<new()>. You You probably want to
override this method and initialise your position there. 

=cut

sub init {
    my $self = shift;
    my $args = @_ && ref($_[0]) ? shift : { @_ };
    my %config = (
        player      => 1,
    );

    @$self{keys %config} = values %config;

    # Override defaults
    while (my ($key, $val) = each %{ $args }) {
        $self->{$key} = $val if exists $self->{$key};
    }

    return $self;
}


=item copy

Clone a position.

=cut

sub copy {
    my $self = shift;
    return dclone($self);
}


=item player [$player]

Read and/or set the current player. If argument is given, that
will be set to the current player.

=cut

sub player {
    my $self = shift;
    $self->{player} = shift if @_;
    return $self->{player};
}



1;  # ensure using this module works
__END__

=back


=head1 SEE ALSO

The author's website, describing this and other projects:
L<http://brautaset.org/software/>


=head1 AUTHOR

Stig Brautaset, E<lt>stig@brautaset.orgE<gt>


=head1 COPYRIGHT AND LICENCE

Copyright (C) 2004, 2005 by Stig Brautaset

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.3 or,
at your option, any later version of Perl 5 you may have available.

=cut

# vim: shiftwidth=4 tabstop=4 softtabstop=4 expandtab