Bio/AnalysisParserI.pm

   1 #---------------------------------------------------------------
   2 #
   3 # BioPerl module Bio::AnalysisParserI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Steve Chervitz <sac@bioperl.org>
   8 #
   9 # Derived from Bio::SeqAnalysisParserI by Jason Stajich, Hilmar Lapp.
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12 #---------------------------------------------------------------
  13
  14 =head1 NAME
  15
  16 Bio::AnalysisParserI - Generic analysis output parser interface
  17
  18 =head1 SYNOPSIS
  19
  20     # get a AnalysisParserI somehow.
  21     # Eventually, there may be an Bio::Factory::AnalysisParserFactory.
  22     # For now a SearchIO object, an implementation of AnalysisParserI, can be created
  23     # directly, as in the following:
  24     my $parser = Bio::SearchIO->new(
  25                                     '-file'   => 'inputfile',
  26                                     '-format' => 'blast');
  27
  28     while( my $result = $parser->next_result() ) {
  29         print "Result:  ", $result->analysis_method,
  30               ", Query:  ", $result->query_name, "\n";
  31
  32           while( my $feature = $result->next_feature() ) {
  33               print "Feature from ", $feature->start, " to ",
  34                     $feature->end, "\n";
  35           }
  36     }
  37
  38 =head1 DESCRIPTION
  39
  40 AnalysisParserI is a interface for describing generic analysis
  41 result parsers. This module makes no assumption about the nature of
  42 analysis being parsed, only that zero or more result sets can be
  43 obtained from the input source.
  44
  45 This module was derived from Bio::SeqAnalysisParserI, the differences being
  46
  47 =over 4
  48
  49 =item 1. next_feature() was replaced with next_result().
  50
  51 Instead of flattening a stream containing potentially multiple
  52 analysis results into a single set of features, AnalysisParserI
  53 segments the stream in terms of analysis result sets
  54 (Bio::AnalysisResultI objects). Each AnalysisResultI can then be
  55 queried for its features (if any) as well as other information
  56 about the result
  57
  58 =item 2. AnalysisParserI is a pure interface.
  59
  60 It does not inherit from Bio::Root::RootI and does not provide a new()
  61 method. Implementations are free to choose how to implement it.
  62
  63 =back
  64
  65 =head2 Rationale (copied from Bio::SeqAnalysisParserI)
  66
  67 The concept behind this interface is to have a generic interface in sequence
  68 annotation pipelines (as used e.g. in high-throughput automated
  69 sequence annotation). This interface enables plug-and-play for new analysis
  70 methods and their corresponding parsers without the necessity for modifying
  71 the core of the annotation pipeline. In this concept the annotation pipeline
  72 has to rely on only a list of methods for which to process the results, and a
  73 factory from which it can obtain the corresponding parser implementing this
  74 interface.
  75
  76 =head2 TODO
  77
  78 Create Bio::Factory::AnalysisParserFactoryI and
  79 Bio::Factory::AnalysisParserFactory for interface and an implementation.
  80 Note that this factory could return Bio::SearchIO-derived objects.
  81
  82 =head1 FEEDBACK
  83
  84 =head2 Mailing Lists
  85
  86 User feedback is an integral part of the evolution of this
  87 and other Bioperl modules. Send your comments and suggestions preferably
  88  to one of the Bioperl mailing lists.
  89 Your participation is much appreciated.
  90
  91   bioperl-l@bioperl.org                  - General discussion
  92   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  93
  94 =head2 Support
  95
  96 Please direct usage questions or support issues to the mailing list:
  97
  98 I<bioperl-l@bioperl.org>
  99
 100 rather than to the module maintainer directly. Many experienced and
 101 reponsive experts will be able look at the problem and quickly
 102 address it. Please include a thorough description of the problem
 103 with code and data examples if at all possible.
 104
 105 =head2 Reporting Bugs
 106
 107 Report bugs to the Bioperl bug tracking system to help us keep track
 108 the bugs and their resolution.  Bug reports can be submitted via the
 109 web:
 110
 111   https://github.com/bioperl/bioperl-live/issues
 112
 113 =head1 AUTHOR - Steve Chervitz, Jason Stajich, Hilmar Lapp
 114
 115 Email sac@bioperl.org
 116
 117 Authors of Bio::SeqAnalysisParserI on which this module is based:
 118 Email jason@bioperl.org
 119 Email hlapp@gmx.net
 120
 121 =head1 COPYRIGHT
 122
 123 Copyright (c) 2001 Steve Chervitz. All Rights Reserved.
 124
 125 =head1 DISCLAIMER
 126
 127 This software is provided "as is" without warranty of any kind.
 128
 129 =head1 APPENDIX
 130
 131 The rest of the documentation details each of the object methods.
 132 Internal methods are usually preceded with a _
 133
 134 =cut
 135
 136 package Bio::AnalysisParserI;
 137 use strict;
 138
 139
 140 use base qw(Bio::Root::RootI);
 141
 142 =head2 next_result
 143
 144  Title   : next_result
 145  Usage   : $result = $obj->next_result();
 146  Function: Returns the next result available from the input, or
 147            undef if there are no more results.
 148  Example :
 149  Returns : A Bio::Search::Result::ResultI implementing object,
 150            or undef if there are no more results.
 151  Args    : none
 152
 153 =cut
 154
 155 sub next_result {
 156     my ($self);
 157     $self->throw_not_implemented;
 158 }
 159
 160
 161 1;
 162 __END__
 163
 164 NOTE (sac): My ten-month old son Russell added the following line.
 165 It doesn't look like it will compile so I'm putting it here:
 166 mt6 j7qa