Bio/Factory/SequenceProcessorI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Factory::SequenceProcessorI
   4 #
   5 # Cared for by Hilmar Lapp <hlapp at gmx.net>
   6 #
   7 # Copyright Hilmar Lapp
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 #
  12 # (c) Hilmar Lapp, hlapp at gmx.net, 2002.
  13 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
  14 #
  15 # You may distribute this module under the same terms as perl itself.
  16 # Refer to the Perl Artistic License (see the license accompanying this
  17 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  18 # for the terms under which you may use, modify, and redistribute this module.
  19 #
  20 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  21 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  22 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  23 #
  24
  25 # POD documentation - main docs before the code
  26
  27 =head1 NAME
  28
  29 Bio::Factory::SequenceProcessorI - Interface for chained sequence
  30                                    processing algorithms
  31
  32 =head1 SYNOPSIS
  33
  34     use Bio::SeqIO;
  35     use MySeqProcessor; # is-a Bio::Factory::SequenceProcessorI
  36
  37     # obtain your source stream, e.g., an EMBL file
  38     my $seqin = Bio::SeqIO->new(-fh => \*STDIN, -format => 'embl');
  39     # create your processor (it must implement this interface)
  40     my $seqalgo = MySeqProcessor->new();
  41     # chain together
  42     $seqalgo->source_stream($seqin);
  43     # you could create more processors and chain them one after another
  44     # ...
  45     # finally, the last link in the chain is your SeqIO stream
  46     my $seqpipe = $seqalgo;
  47
  48     # once you've established the pipeline, proceed as if you had a
  49     # single SeqIO stream
  50     while(my $seq = $seqpipe->next_seq()) {
  51         # ... do something ...
  52     }
  53
  54 =head1 DESCRIPTION
  55
  56 This defines an interface that allows seamless chaining of sequence
  57 processing algorithms encapsulated in modules while retaining the
  58 overall Bio::SeqIO interface at the end of the pipeline.
  59
  60 This is especially useful if you want an easily configurable
  61 processing pipeline of re-usable algorithms as building blocks instead
  62 of (hard-)coding the whole algorithm in a single script.
  63
  64 There are literally no restrictions as to what an individual module
  65 can do with a sequence object it obtains from the source stream before
  66 it makes it available through its own next_seq() method. It can
  67 manipulate the sequence object, but otherwise keep it intact, but it
  68 can also create any number of new sequence objects from it, or it can
  69 discard some, or any combination thereof. The only requirement is that
  70 its next_seq() method return Bio::PrimarySeqI compliant objects. In
  71 order to play nice, if a processor creates new objects it should try
  72 to use the same sequence factory that the source stream uses, but this
  73 is not strongly mandated.
  74
  75 =head1 FEEDBACK
  76
  77 =head2 Mailing Lists
  78
  79 User feedback is an integral part of the evolution of this and other
  80 Bioperl modules. Send your comments and suggestions preferably to
  81 the Bioperl mailing list.  Your participation is much appreciated.
  82
  83   bioperl-l@bioperl.org                  - General discussion
  84   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  85
  86 =head2 Reporting Bugs
  87
  88 Report bugs to the Bioperl bug tracking system to help us keep track
  89 of the bugs and their resolution. Bug reports can be submitted via the
  90 web:
  91
  92   http://bugzilla.open-bio.org/
  93
  94 =head1 AUTHOR - Hilmar Lapp
  95
  96 Email hlapp at gmx.net
  97
  98 =head1 APPENDIX
  99
 100 The rest of the documentation details each of the object methods.
 101 Internal methods are usually preceded with a _
 102
 103 =cut
 104
 105
 106 # Let the code begin...
 107
 108
 109 package Bio::Factory::SequenceProcessorI;
 110 use strict;
 111 use Bio::Root::RootI;
 112
 113 use base qw(Bio::Factory::SequenceStreamI);
 114
 115 =head2 source_stream
 116
 117  Title   : source_stream
 118  Usage   : $obj->source_stream($newval)
 119  Function: Get/set the source sequence stream for this sequence
 120            processor.
 121
 122            An implementation is not required to allow set, but will
 123            usually do so.
 124
 125  Example :
 126  Returns : A Bio::Factory::SequenceStreamI compliant object
 127  Args    : on set, new value (a Bio::Factory::SequenceStreamI compliant
 128            object)
 129
 130
 131 =cut
 132
 133 sub source_stream{
 134     shift->throw_not_implemented();
 135 }
 136
 137 =head1 Bio::Factory::SequenceStreamI methods
 138
 139  The requirement to implement these methods is inherited from
 140  L<Bio::Factory::SequenceStreamI>. An implementation may not
 141  necessarily have to implement all methods in a meaningful way. Which
 142  methods will be necessary very much depends on the context in which
 143  an implementation of this interface is used. E.g., if it is only used
 144  for post-processing sequences read from a SeqIO stream, write_seq()
 145  will not be used and hence does not need to be implemented in a
 146  meaningful way (it may in fact even throw an exception).
 147
 148  Also, since an implementor will already receive built objects from a
 149  sequence stream, sequence_factory() may or may not be relevant,
 150  depending on whether the processing method does or does not involve
 151  creating new objects.
 152
 153 =cut
 154
 155 =head2 next_seq
 156
 157  Title   : next_seq
 158  Usage   : $seq = stream->next_seq
 159  Function: Reads the next sequence object from the stream and returns it.
 160
 161            In the case of a non-recoverable situation an exception
 162            will be thrown.  Do not assume that you can resume parsing
 163            the same stream after catching the exception. Note that you
 164            can always turn recoverable errors into exceptions by
 165            calling $stream->verbose(2).
 166
 167  Returns : a Bio::Seq sequence object
 168  Args    : none
 169
 170 See L<Bio::Root::RootI>
 171
 172 =cut
 173
 174 =head2 write_seq
 175
 176  Title   : write_seq
 177  Usage   : $stream->write_seq($seq)
 178  Function: writes the $seq object into the stream
 179  Returns : 1 for success and 0 for error
 180  Args    : Bio::Seq object
 181
 182 =cut
 183
 184 =head2 sequence_factory
 185
 186  Title   : sequence_factory
 187  Usage   : $seqio->sequence_factory($seqfactory)
 188  Function: Get the Bio::Factory::SequenceFactoryI
 189  Returns : Bio::Factory::SequenceFactoryI
 190  Args    : none
 191
 192
 193 =cut
 194
 195 1;