Bio/Symbol/AlphabetI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Symbol::AlphabetI
   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::AlphabetI - A Symbol Alphabet
  18
  19 =head1 SYNOPSIS
  20
  21     # get a Bio::Symbol::AlphabetI object somehow
  22     my @symbols = $alphabet->symbols;
  23     my @subalphas = $alphabet->alphabets;
  24     if( $alphabet->contains($symbol) ) {
  25         # do something
  26     }
  27
  28 =head1 DESCRIPTION
  29
  30 Alphabet contains set of symbols, which can be concatenated to form
  31 symbol lists. Sequence string, for example, is stringified
  32 representation of the symbol list (tokens of symbols).
  33
  34 This module was implemented for the purposes of meeting the
  35 BSANE/BioCORBA spec 0.3 only.
  36
  37 =head1 FEEDBACK
  38
  39 =head2 Mailing Lists
  40
  41 User feedback is an integral part of the evolution of this and other
  42 Bioperl modules. Send your comments and suggestions preferably to
  43 the Bioperl mailing list.  Your participation is much appreciated.
  44
  45   bioperl-l@bioperl.org                  - General discussion
  46   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  47
  48 =head2 Support
  49
  50 Please direct usage questions or support issues to the mailing list:
  51
  52 L<bioperl-l@bioperl.org>
  53
  54 rather than to the module maintainer directly. Many experienced and
  55 reponsive experts will be able look at the problem and quickly
  56 address it. Please include a thorough description of the problem
  57 with code and data examples if at all possible.
  58
  59 =head2 Reporting Bugs
  60
  61 Report bugs to the Bioperl bug tracking system to help us keep track
  62 of the bugs and their resolution. Bug reports can be submitted via the
  63 web:
  64
  65   http://bugzilla.open-bio.org/
  66
  67 =head1 AUTHOR - Jason Stajich
  68
  69 Email jason@bioperl.org
  70
  71 =head1 APPENDIX
  72
  73 The rest of the documentation details each of the object methods.
  74 Internal methods are usually preceded with a _
  75
  76 =cut
  77
  78 # Let the code begin...
  79
  80 package Bio::Symbol::AlphabetI;
  81 use strict;
  82 use Bio::Root::RootI;
  83
  84 =head2 AlphabetI Interface methods
  85
  86 =cut
  87
  88 =head2 symbols
  89
  90  Title   : symbols
  91  Usage   : my @symbols = $alphabet->symbols();
  92  Function: Get/Set Symbol list for an alphabet
  93            List of symbols, which make up this alphabet.
  94  Returns : Array of L<Bio::Symbol::SymbolI> objects
  95  Args    : (optional) Array of L<Bio::Symbol::SymbolI> objects
  96
  97 =cut
  98
  99 sub symbols{
 100    my ($self,@args) = @_;
 101    $self->throw_not_implemented();
 102 }
 103
 104 =head2 alphabets
 105
 106  Title   : alphabets
 107  Usage   : my @alphabets = $alphabet->alphabets();
 108  Function: Get/Set Sub Alphabet list for an alphabet
 109            Sub-alphabets. E.g. codons made from DNAxDNAxDNA alphabets
 110  Returns : Array of L<Bio::Symbol::AlphabetI> objects
 111  Args    : (optional) Array of L<Bio::Symbol::AlphabetI> objects
 112
 113 =cut
 114
 115 sub alphabets{
 116     my ($self,@args) = @_;
 117     $self->throw_not_implemented();
 118 }
 119
 120 =head2 contains
 121
 122  Title   : contains
 123  Usage   : if($alphabet->contains($symbol)) { }
 124  Function: Tests of Symbol is contained in this alphabet
 125  Returns : Boolean
 126  Args    : L<Bio::Symbol::SymbolI>
 127
 128 =cut
 129
 130 sub contains{
 131    my ($self,@args) = @_;
 132    $self->throw_not_implemented();
 133 }
 134
 135 # Other methods from BSANE - not sure if we will implement here or only in
 136 # BioCORBA implementation
 137
 138 # Resolve symbols from the token string.
 139 #    SymbolList to_symbol(in string tokens) raises ( IllegalSymbolException) ;
 140
 141 # Convinience method, which returns gap symbol that do not
 142 # match with any other symbols in the alphabet.
 143 #   Symbol get_gap_symbol() raises ( DoesNotExist) ;
 144
 145
 146 # Returns a ambiguity symbol, which represent list of
 147 # symbols. All symbols in a list must be members of
 148 # this alphabet otherwise IllegalSymbolException is
 149 # thrown.
 150 # Symbol get_ambiguity( in SymbolList symbols) raises( IllegalSymbolException);
 151
 152
 153 #  Returns a Symbol, which represents ordered list of symbols
 154 #  given as a parameter. Each symbol in the list must be member of
 155 #  different sub-alphabet in the order defined by the alphabets
 156 #  attribute. For example, codons can be represented by a compound
 157 #  Alphabet of three DNA Alphabets, in which case the get_symbol(
 158 #  SymbolList[ a,g,t]) method of the Alphabet returns Symbol for
 159 #  the codon agt.<p>
 160
 161 #  IllegalSymbolException is raised if members of symbols
 162 #  are not Symbols over the alphabet defined by
 163 #  get_alphabets()-method
 164 #  Symbol get_symbol(in SymbolList symbols) raises(IllegalSymbolException) ;
 165
 166 1;