Bio/Seq/BaseSeqProcessor.pm

   1 #
   2 # BioPerl module for Bio::Seq::BaseSeqProcessor
   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::Seq::BaseSeqProcessor - Base implementation for a SequenceProcessor
  31
  32 =head1 SYNOPSIS
  33
  34     # you need to derive your own processor from this one
  35
  36 =head1 DESCRIPTION
  37
  38 This provides just a basic framework for implementations of
  39 L<Bio::Factory::SequenceProcessorI>.
  40
  41 Essentially what it does is support a parameter to new() to set
  42 sequence factory and source stream, and a next_seq() implementation
  43 that will use a queue to be filled by a class overriding
  44 process_seq().
  45
  46 =head1 FEEDBACK
  47
  48 =head2 Mailing Lists
  49
  50 User feedback is an integral part of the evolution of this and other
  51 Bioperl modules. Send your comments and suggestions preferably to
  52 the Bioperl mailing list.  Your participation is much appreciated.
  53
  54   bioperl-l@bioperl.org                  - General discussion
  55   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  56
  57 =head2 Support
  58
  59 Please direct usage questions or support issues to the mailing list:
  60
  61 I<bioperl-l@bioperl.org>
  62
  63 rather than to the module maintainer directly. Many experienced and
  64 reponsive experts will be able look at the problem and quickly
  65 address it. Please include a thorough description of the problem
  66 with code and data examples if at all possible.
  67
  68 =head2 Reporting Bugs
  69
  70 Report bugs to the Bioperl bug tracking system to help us keep track
  71 of the bugs and their resolution. Bug reports can be submitted via the
  72 web:
  73
  74   https://github.com/bioperl/bioperl-live/issues
  75
  76 =head1 AUTHOR - Hilmar Lapp
  77
  78 Email hlapp at gmx.net
  79
  80 =head1 APPENDIX
  81
  82 The rest of the documentation details each of the object methods.
  83 Internal methods are usually preceded with a _
  84
  85 =cut
  86
  87
  88 # Let the code begin...
  89
  90
  91 package Bio::Seq::BaseSeqProcessor;
  92 use strict;
  93
  94 # Object preamble - inherits from Bio::Root::Root
  95
  96
  97 use base qw(Bio::Root::Root Bio::Factory::SequenceProcessorI);
  98
  99 =head2 new
 100
 101  Title   : new
 102  Usage   : my $obj = Bio::Seq::BaseSeqProcessor->new();
 103  Function: Builds a new Bio::Seq::BaseSeqProcessor object
 104  Returns : an instance of Bio::Seq::BaseSeqProcessor
 105  Args    : Named parameters. Currently supported are
 106              -seqfactory  the Bio::Factory::SequenceFactoryI object to use
 107              -source_stream the Bio::Factory::SequenceStreamI object to
 108                           which we are chained
 109
 110
 111 =cut
 112
 113 sub new {
 114     my($class,@args) = @_;
 115
 116     my $self = $class->SUPER::new(@args);
 117
 118     my ($stream,$fact) =
 119         $self->_rearrange([qw(SOURCE_STREAM SEQFACTORY)], @args);
 120
 121     $self->{'_queue'} = [];
 122     $self->sequence_factory($fact) if $fact;
 123     $self->source_stream($stream) if $stream;
 124
 125     return $self;
 126 }
 127
 128 =head1 L<Bio::Factory::SequenceProcessorI> methods
 129
 130 =cut
 131
 132 =head2 source_stream
 133
 134  Title   : source_stream
 135  Usage   : $obj->source_stream($newval)
 136  Function: Get/set the source sequence stream for this sequence
 137            processor.
 138
 139  Example :
 140  Returns : A Bio::Factory::SequenceStreamI compliant object
 141  Args    : on set, new value (a Bio::Factory::SequenceStreamI compliant
 142            object)
 143
 144
 145 =cut
 146
 147 sub source_stream{
 148     my $self = shift;
 149
 150     if(@_) {
 151         my $stream = shift;
 152         my $fact = $stream->sequence_factory();
 153         $self->sequence_factory($fact)
 154             unless $self->sequence_factory() || (! $fact);
 155         return $self->{'source_stream'} = $stream;
 156     }
 157     return $self->{'source_stream'};
 158 }
 159
 160 =head1 L<Bio::Factory::SequenceStreamI> methods
 161
 162 =cut
 163
 164 =head2 next_seq
 165
 166  Title   : next_seq
 167  Usage   : $seq = stream->next_seq
 168  Function: Reads the next sequence object from the stream and returns it.
 169
 170            This implementation will obtain objects from the source
 171            stream as necessary and pass them to process_seq() for
 172            processing. This method will return the objects one at a
 173            time that process_seq() returns.
 174
 175  Returns : a Bio::Seq sequence object
 176  Args    : none
 177
 178 See L<Bio::Factory::SequenceStreamI::next_seq>
 179
 180 =cut
 181
 182 sub next_seq{
 183     my $self = shift;
 184     my $seq;
 185
 186     # if the queue is empty, fetch next from source and process it
 187     if(@{$self->{'_queue'}} == 0) {
 188         my @seqs = ();
 189         while($seq = $self->source_stream->next_seq()) {
 190             @seqs = $self->process_seq($seq);
 191             # we may get zero seqs returned
 192             last if @seqs;
 193         }
 194         push(@{$self->{'_queue'}}, @seqs) if @seqs;
 195     }
 196     # take next from the queue of seqs
 197     $seq = shift(@{$self->{'_queue'}});
 198     return $seq;
 199 }
 200
 201 =head2 write_seq
 202
 203  Title   : write_seq
 204  Usage   : $stream->write_seq($seq)
 205  Function: Writes the result(s) of processing the sequence object into
 206            the stream.
 207
 208            You need to override this method in order not to alter
 209            (process) sequence objects before output.
 210
 211  Returns : 1 for success and 0 for error. The method stops attempting
 212            to write objects after the first error returned from the
 213            source stream. Otherwise the return value is the value
 214            returned from the source stream from writing the last
 215            object resulting from processing the last sequence object
 216            given as argument.
 217
 218  Args    : Bio::SeqI object, or an array of such objects
 219
 220 =cut
 221
 222 sub write_seq{
 223     my ($self, @seqs) = @_;
 224     my $ret;
 225     foreach my $seq (@seqs) {
 226         foreach my $processed ($self->process_seq($seq)) {
 227             $ret = $self->source_stream->write_seq($seq);
 228             return unless $ret;
 229         }
 230     }
 231     return $ret;
 232 }
 233
 234 =head2 sequence_factory
 235
 236  Title   : sequence_factory
 237  Usage   : $seqio->sequence_factory($seqfactory)
 238  Function: Get the Bio::Factory::SequenceFactoryI
 239  Returns : Bio::Factory::SequenceFactoryI
 240  Args    : none
 241
 242
 243 =cut
 244
 245 sub sequence_factory{
 246     my $self = shift;
 247
 248     return $self->{'sequence_factory'} = shift if @_;
 249     return $self->{'sequence_factory'};
 250 }
 251
 252 =head2 object_factory
 253
 254  Title   : object_factory
 255  Usage   : $obj->object_factory($newval)
 256  Function: This is an alias to sequence_factory with a more generic name.
 257  Example :
 258  Returns : a L<Bio::Factory::ObjectFactoryI> compliant object
 259  Args    : on set, new value (a L<Bio::Factory::ObjectFactoryI>
 260            compliant object or undef, optional)
 261
 262
 263 =cut
 264
 265 sub object_factory{
 266     return shift->sequence_factory(@_);
 267 }
 268
 269 =head2 close
 270
 271  Title   : close
 272  Usage   :
 273  Function: Closes the stream. We override this here in order to cascade
 274            to the source stream.
 275  Example :
 276  Returns :
 277  Args    : none
 278
 279
 280 =cut
 281
 282 sub close{
 283     my $self = shift;
 284     return $self->source_stream() ? $self->source_stream->close(@_) : 1;
 285 }
 286
 287 =head1 To be overridden by a derived class
 288
 289 =cut
 290
 291 =head2 process_seq
 292
 293  Title   : process_seq
 294  Usage   :
 295  Function: This is the method that is supposed to do the actual
 296            processing. It needs to be overridden to do what you want
 297            it to do.
 298
 299            Generally, you do not have to override or implement any other
 300            method to derive your own sequence processor.
 301
 302            The implementation provided here just returns the unaltered
 303            input sequence and hence is not very useful other than
 304            serving as a neutral default processor.
 305
 306  Example :
 307  Returns : An array of zero or more Bio::PrimarySeqI (or derived
 308            interface) compliant object as the result of processing the
 309            input sequence.
 310  Args    : A Bio::PrimarySeqI (or derived interface) compliant object
 311            to be processed.
 312
 313
 314 =cut
 315
 316 sub process_seq{
 317     my ($self,$seq) = @_;
 318
 319     return ($seq);
 320 }
 321
 322 1;