Bio/Factory/SequenceProcessorI.pm

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