lib/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://github.com/bioperl/bioperl-live/issues
 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
 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;