Bio/Factory/SequenceProcessorI.pm

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