branch-1-6/Bio/Symbol/Alphabet.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Symbol::Alphabet
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Jason Stajich <jason@bioperl.org>
   8 #
   9 # Copyright Jason Stajich
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::Symbol::Alphabet - BSANE/BioCORBA compliant symbol list alphabet
  18
  19 =head1 SYNOPSIS
  20
  21   {
  22       my $alphabet = Bio::Symbols::Alphabet->new(-symbols => [ @s ],
  23                                                 -subalphabets => [ @alphas ] );
  24
  25       my @symbols = $alphabet->symbols;
  26       my @subalphas = $alphabet->alphabets;
  27       if( $alphabet->contains($symbol) ) {
  28           # do something
  29       }
  30   }
  31
  32 =head1 DESCRIPTION
  33
  34 Alphabet contains set of symbols, which can be concatenated to
  35 form symbol lists. Sequence string, for example, is stringified
  36 representation of the symbol list (tokens of symbols).
  37
  38 This module was implemented for the purposes of meeting the
  39 BSANE/BioCORBA spec 0.3 only.
  40
  41 =head1 FEEDBACK
  42
  43 =head2 Mailing Lists
  44
  45 User feedback is an integral part of the evolution of this and other
  46 Bioperl modules. Send your comments and suggestions preferably to
  47 the Bioperl mailing list.  Your participation is much appreciated.
  48
  49   bioperl-l@bioperl.org                  - General discussion
  50   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  51
  52 =head2 Support
  53
  54 Please direct usage questions or support issues to the mailing list:
  55
  56 I<bioperl-l@bioperl.org>
  57
  58 rather than to the module maintainer directly. Many experienced and
  59 reponsive experts will be able look at the problem and quickly
  60 address it. Please include a thorough description of the problem
  61 with code and data examples if at all possible.
  62
  63 =head2 Reporting Bugs
  64
  65 Report bugs to the Bioperl bug tracking system to help us keep track
  66 of the bugs and their resolution. Bug reports can be submitted via the
  67 web:
  68
  69   http://bugzilla.open-bio.org/
  70
  71 =head1 AUTHOR - Jason Stajich
  72
  73 Email jason@bioperl.org
  74
  75 =head1 APPENDIX
  76
  77 The rest of the documentation details each of the object methods.
  78 Internal methods are usually preceded with a _
  79
  80 =cut
  81
  82
  83 # Let the code begin...
  84
  85
  86 package Bio::Symbol::Alphabet;
  87 use strict;
  88
  89 # Object preamble - inherits from Bio::Root::Root
  90
  91
  92 use base qw(Bio::Root::Root Bio::Symbol::AlphabetI);
  93
  94 =head2 new
  95
  96  Title   : new
  97  Usage   : my $obj = Bio::Symbol::Alphabet->new();
  98  Function: Builds a new Bio::Symbol::Alphabet object
  99  Returns : Bio::Symbol::Alphabet
 100  Args    : -symbols  => Array ref of Bio::Symbol::SymbolI objects
 101            -subalphas=> Array ref of Bio::Symbol::AlphabetI objects
 102                         representing sub alphabets
 103
 104 =cut
 105
 106 sub new {
 107     my($class,@args) = @_;
 108
 109     my $self = $class->SUPER::new(@args);
 110     $self->{'_symbols'} = [];
 111     $self->{'_alphabets'} = [];
 112     my ($symbols, $subalphas) = $self->_rearrange([qw(SYMBOLS SUBALPHAS)],
 113                                                   @args);
 114
 115     defined $symbols && ref($symbols) =~ /array/i && $self->symbols(@$symbols);
 116     defined $subalphas && ref($subalphas) =~ /array/i && $self->alphabets(@$subalphas);
 117     return $self;
 118 }
 119
 120 =head2 AlphabetI Interface methods
 121
 122 =cut
 123
 124 =head2 symbols
 125
 126  Title   : symbols
 127  Usage   : my @symbols = $alphabet->symbols();
 128  Function: Get/Set Symbol list for an alphabet
 129            List of symbols, which make up this alphabet.
 130  Returns : Array of Bio::Symbol::SymbolI objects
 131  Args    : (optionalalphabets) Array of Bio::Symbol::SymbolI objects
 132
 133 =cut
 134
 135 sub symbols {
 136     my ($self,@args) = @_;
 137     if( @args ) {
 138         $self->{'_symbols'} = [];
 139         foreach my $symbol ( @args ) {
 140             if( ! defined $symbol || ! ref($symbol) ||
 141                 ! $symbol->isa('Bio::Symbol::SymbolI') ) {
 142                 $self->warn("Did not provide a proper Bio::Symbol::SymbolI to method 'symbols' (got $symbol)");
 143             } else {
 144                 push @{$self->{'_symbols'}}, $symbol;
 145             }
 146         }
 147     }
 148     return @{$self->{'_symbols'}};
 149 }
 150
 151 =head2 alphabets
 152
 153  Title   : alphabets
 154  Usage   : my @alphabets = $alphabet->alphabets();
 155  Function: Get/Set Sub Alphabet list for an alphabet
 156            Sub-alphabets. E.g. codons made from DNAxDNAxDNA alphabets
 157  Returns : Array of Bio::Symbol::AlphabetI objects
 158  Args    : (optional) Array of Bio::Symbol::AlphabetI objects
 159
 160 =cut
 161
 162 sub alphabets {
 163     my ($self,@args) = @_;
 164    if( @args ) {
 165        $self->{'_alphabets'} = [];
 166        foreach my $alpha ( @args ) {
 167            if( ! $alpha->isa('Bio::Symbol::AlphabetI') ) {
 168                $self->warn("Did not provide a proper Bio::Symbol::AlphabetI to method 'alphabets' (got $alpha)");
 169            } else {
 170                push @{$self->{'_alphabets'}}, $alpha;
 171            }
 172        }
 173    }
 174     return @{$self->{'_alphabets'}};
 175 }
 176
 177 =head2 contains
 178
 179  Title   : contains
 180  Usage   : if($alphabet->contains($symbol)) { }
 181  Function: Tests of Symbol is contained in this alphabet
 182  Returns : Boolean
 183  Args    : Bio::Symbol::SymbolI
 184
 185 =cut
 186
 187 sub contains{
 188    my ($self,$testsymbol) = @_;
 189    foreach my $symbol ( $self->symbols ) {
 190        return 1 if( $symbol->equals($testsymbol) );
 191    }
 192    return 0;
 193 }
 194
 195 1;