package Bio::CDAT::VOS::CharMatrixI;
use Bio::Phylo::Util::Exceptions;
use strict;
use vars qw(@ISA);

# One line so MakeMaker sees it.
use Bio::Phylo; our $VERSION = $Bio::Phylo::VERSION;

my $class = 'Bio::Matrix::MatrixI';
eval { require $class };
if ( not $@ ) {
    @ISA = qw(Bio::Matrix::MatrixI);
}


=head1 NAME

Bio::CDAT::VOS::CharMatrixI - Abstract interface for character state matrices

=head1 SYNOPSIS

 No direct usage. This interface is implemented by character state matrices
 such as those imported through CIPRES CORBA or from a nexus file.

=head1 DESCRIPTION

This interface is meant to allow for polymorphic behaviour of character state
matrix objects (e.g. DNA versus STANDARD data types) without the need for
cascades of UNIVERSAL::isa tests. The underlying implementations can of course
differ: this interface is agnostic w.r.t. data structures, so data structures
can be either those coming in from CIPRES, or whatever is handiest when parsing
text files or importing from a database.

=head1 INTERFACE METHODS (ACCESSORS)

=over

=item get_type()

 Type    : Accessor
 Title   : get_type
 Usage   : my $type = $matrix->get_type();
 Function: Returns a matrix's data type.
 Returns : one of [DNA|RNA|STANDARD|
           PROTEIN|NUCLEOTIDE|CONTINUOUS].
 Args    : NONE

=cut

sub get_type {
    my ($self) = @_;
    if ( $self->isa('Bio::Root::RootI') ) {
        $self->throw_not_implemented();
    }
    else {
        Bio::Phylo::Util::Exceptions::NotImplemented->throw(
            'error' => 'Attempt to call interface method',
        );
    }
}

=item get_symbols()

 Type    : Accessor
 Title   : get_symbols
 Usage   : my @symbols = @{ $matrix->get_symbols() };
 Function: Returns an array ref
           of allowed symbols
 Returns : ARRAY
 Args    : NONE

=cut

sub get_symbols {
    my ($self) = @_;
    if ( $self->isa('Bio::Root::RootI') ) {
        $self->throw_not_implemented();
    }
    else {
        Bio::Phylo::Util::Exceptions::NotImplemented->throw(
            'error' => 'Attempt to call interface method',
        );
    }
}

=item get_missing()

 Type    : Accessor
 Title   : get_missing
 Usage   : my $missing = $matrix->get_missing();
 Function: Returns the missing character symbol.
 Returns : SCALAR
 Args    : NONE

=cut

sub get_missing {
    my ($self) = @_;
    if ( $self->isa('Bio::Root::RootI') ) {
        $self->throw_not_implemented();
    }
    else {
        Bio::Phylo::Util::Exceptions::NotImplemented->throw(
            'error' => 'Attempt to call interface method',
        );
    }
}

=item get_gap()

 Type    : Accessor
 Title   : get_gap
 Usage   : my $gap = $matrix->get_gap();
 Function: Returns the gap (indel?) character symbol.
 Returns : SCALAR
 Args    : NONE

=cut

sub get_gap {
    my ($self) = @_;
    if ( $self->isa('Bio::Root::RootI') ) {
        $self->throw_not_implemented();
    }
    else {
        Bio::Phylo::Util::Exceptions::NotImplemented->throw(
            'error' => 'Attempt to call interface method',
        );
    }
}

=item get_ntax()

 Type    : Accessor
 Title   : get_ntax
 Usage   : my $ntax = $matrix->get_ntax();
 Function: Returns number of taxa (rows) in matrix
 Returns : INT
 Args    : NONE

=cut

sub get_ntax {
    my ($self) = @_;
    if ( $self->isa('Bio::Root::RootI') ) {
        $self->throw_not_implemented();
    }
    else {
        Bio::Phylo::Util::Exceptions::NotImplemented->throw(
            'error' => 'Attempt to call interface method',
        );
    }
}

=item get_nchar()

 Type    : Accessor
 Title   : get_nchar
 Usage   : my $nchar = $matrix->get_nchar();
 Function: Returns number of characters (columns) in matrix
 Returns : INT
 Args    : NONE

=cut

sub get_nchar {
    my ($self) = @_;
    if ( $self->isa('Bio::Root::RootI') ) {
        $self->throw_not_implemented();
    }
    else {
        Bio::Phylo::Util::Exceptions::NotImplemented->throw(
            'error' => 'Attempt to call interface method',
        );
    }
}

=item get_charlabels()

 Type    : Accessor
 Title   : get_charlabels
 Usage   : my @labels = @{ $matrix->get_charlabels() };
 Function: Returns character (column) labels in matrix
 Returns : ARRAY
 Args    : NONE

=cut

sub get_charlabels {
    my ($self) = @_;
    if ( $self->isa('Bio::Root::RootI') ) {
        $self->throw_not_implemented();
    }
    else {
        Bio::Phylo::Util::Exceptions::NotImplemented->throw(
            'error' => 'Attempt to call interface method',
        );
    }
}


=back

=head1 SEE ALSO

=over

=item L<Bio::Matrix::MatrixI>

If Bio::Matrix::MatrixI is installed on your system, 
Bio::CDAT::VOS::CharMatrixI inherits from it.

=item L<Bio::Phylo::Matrices::Matrix>

This interface is implemented by L<Bio::Phylo::Matrices::Matrix>.

=item L<Bio::Phylo::Manual>

Also see the manual: L<Bio::Phylo::Manual>.

=back

=head1 FORUM

CPAN hosts a discussion forum for Bio::Phylo. If you have trouble
using this module the discussion forum is a good place to start
posting questions (NOT bug reports, see below):
L<http://www.cpanforum.com/dist/Bio-Phylo>

=head1 BUGS

Please report any bugs or feature requests to C<< bug-bio-phylo@rt.cpan.org >>,
or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bio-Phylo>. I will be notified,
and then you'll automatically be notified of progress on your bug as I make
changes. Be sure to include the following in your request or comment, so that
I know what version you're using:

$Id: CharMatrixI.pm 2263 2006-09-20 22:38:05Z rvosa $

=head1 AUTHOR

Rutger A. Vos,

=over

=item email: C<< rvosa@sfu.ca >>

=item web page: L<http://www.sfu.ca/~rvosa/>

=back

=head1 ACKNOWLEDGEMENTS

The author would like to thank Jason Stajich for many ideas borrowed
from BioPerl L<http://www.bioperl.org>, and CIPRES
L<http://www.phylo.org> and FAB* L<http://www.sfu.ca/~fabstar>
for comments and requests.

=head1 COPYRIGHT & LICENSE

Copyright 2005 Rutger A. Vos, All Rights Reserved. This program is free
software; you can redistribute it and/or modify it under the same terms as Perl
itself.

=cut

1;