lib/Bio/SearchIO/EventHandlerI.pm

   1 #
   2 # BioPerl module for Bio::SearchIO::EventHandlerI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Jason Stajich <jason@bioperl.org>
   7 #
   8 # Copyright Jason Stajich
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::SearchIO::EventHandlerI - An abstract Event Handler for Search Result parsing
  17
  18 =head1 SYNOPSIS
  19
  20 # do not use this object directly it is an interface
  21 # See Bio::SearchIO::SearchResultEventBuilder for an implementation
  22
  23     use Bio::SearchIO::SearchResultEventBuilder;
  24     my $handler = Bio::SearchIO::SearchResultEventBuilder->new();
  25
  26 =head1 DESCRIPTION
  27
  28 This interface describes the basic methods needed to handle Events
  29 thrown from parsing a Search Result such as FASTA, BLAST, or HMMer.
  30
  31 =head1 FEEDBACK
  32
  33 =head2 Mailing Lists
  34
  35 User feedback is an integral part of the evolution of this and other
  36 Bioperl modules. Send your comments and suggestions preferably to
  37 the Bioperl mailing list.  Your participation is much appreciated.
  38
  39   bioperl-l@bioperl.org                  - General discussion
  40   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  41
  42 =head2 Support
  43
  44 Please direct usage questions or support issues to the mailing list:
  45
  46 I<bioperl-l@bioperl.org>
  47
  48 rather than to the module maintainer directly. Many experienced and
  49 reponsive experts will be able look at the problem and quickly
  50 address it. Please include a thorough description of the problem
  51 with code and data examples if at all possible.
  52
  53 =head2 Reporting Bugs
  54
  55 Report bugs to the Bioperl bug tracking system to help us keep track
  56 of the bugs and their resolution. Bug reports can be submitted via the
  57 web:
  58
  59   https://github.com/bioperl/bioperl-live/issues
  60
  61 =head1 AUTHOR - Jason Stajich
  62
  63 Email jason-at-bioperl.org
  64
  65 =head1 APPENDIX
  66
  67 The rest of the documentation details each of the object methods.
  68 Internal methods are usually preceded with a _
  69
  70 =cut
  71
  72
  73 # Let the code begin...
  74
  75
  76 package Bio::SearchIO::EventHandlerI;
  77 use strict;
  78 use Carp;
  79
  80
  81 use base qw(Bio::Event::EventHandlerI);
  82
  83 =head2 start_result
  84
  85  Title   : start_result
  86  Usage   : $handler->start_result($data)
  87  Function: Begins a result event cycle
  88  Returns : none
  89  Args    : Type of Result
  90
  91 =cut
  92
  93 sub start_result {
  94     my ($self) = @_;
  95     $self->throw_not_implemented();
  96 }
  97
  98 =head2 end_result
  99
 100  Title   : end_result
 101  Usage   : $handler->end_result($data)
 102  Function: Ends a result event cycle
 103  Returns : Bio::Search::Result::ResultI object
 104  Args    : none
 105
 106
 107 =cut
 108
 109 sub end_result{
 110    my ($self,@args) = @_;
 111    $self->throw_not_implemented();
 112 }
 113
 114 =head2 start_hsp
 115
 116  Title   : start_hsp
 117  Usage   : $handler->start_hsp($data)
 118  Function: Start a HSP event cycle
 119  Returns : none
 120  Args    : type of element
 121            associated hashref
 122
 123 =cut
 124
 125 sub start_hsp{
 126    my ($self,@args) = @_;
 127    $self->throw_not_implemented();
 128 }
 129
 130 =head2 end_hsp
 131
 132  Title   : end_hsp
 133  Usage   : $handler->end_hsp()
 134  Function: Ends a HSP event cycle
 135  Returns : Bio::Search::HSP::HSPI object
 136  Args    : type of event and associated hashref
 137
 138 =cut
 139
 140 sub end_hsp{
 141    my ($self,@args) = @_;
 142    $self->throw_not_implemented();
 143 }
 144
 145 =head2 start_hit
 146
 147  Title   : start_hit
 148  Usage   : $handler->start_hit()
 149  Function: Starts a Hit event cycle
 150  Returns : none
 151  Args    : type of event and associated hashref
 152
 153
 154 =cut
 155
 156 sub start_hit {
 157    my ($self,@args) = @_;
 158    $self->throw_not_implemented
 159 }
 160
 161 =head2 end_hit
 162
 163  Title   : end_hit
 164  Usage   : $handler->end_hit()
 165  Function: Ends a Hit event cycle
 166  Returns : Bio::Search::Hit::HitI object
 167  Args    : type of event and associated hashref
 168
 169
 170 =cut
 171
 172 sub end_hit {
 173    my ($self,@args) = @_;
 174    $self->throw_not_implemented();
 175 }
 176
 177 =head2 start_iteration
 178
 179  Title   : start_iteration
 180  Usage   : $handler->start_iteration()
 181  Function: Starts an Iteration event cycle
 182  Returns : none
 183  Args    : type of event and associated hashref
 184
 185
 186 =cut
 187
 188 sub start_iteration {
 189    my ($self,@args) = @_;
 190    $self->throw_not_implemented
 191 }
 192
 193 =head2 end_iteration
 194
 195  Title   : end_iteration
 196  Usage   : $handler->end_iteration()
 197  Function: Ends an Iterationevent cycle
 198  Returns : Bio::Search::Iteration::IterationI object
 199  Args    : type of event and associated hashref
 200
 201
 202 =cut
 203
 204 sub end_iteration {
 205    my ($self,@args) = @_;
 206    $self->throw_not_implemented();
 207 }
 208
 209 =head2 register_factory
 210
 211  Title   : register_factory
 212  Usage   : $handler->register_factory('TYPE',$factory);
 213  Function: Register a specific factory for a object type class
 214  Returns : none
 215  Args    : string representing the class and
 216            Bio::Factory::ObjectFactoryI
 217
 218 See L<Bio::Factory::ObjectFactoryI> for more information
 219
 220 =cut
 221
 222 sub register_factory{
 223    my ($self,@args) = @_;
 224    $self->throw_not_implemented();
 225 }
 226
 227
 228 =head2 factory
 229
 230  Title   : factory
 231  Usage   : my $f = $handler->factory('TYPE');
 232  Function: Retrieves the associated factory for requested 'TYPE'
 233  Returns : a Bio::Factory::ObjectFactoryI
 234  Throws  : Bio::Root::BadParameter if none registered for the supplied type
 235  Args    : name of factory class to retrieve
 236
 237 See L<Bio::Factory::ObjectFactoryI> for more information
 238
 239 =cut
 240
 241 sub factory{
 242    my ($self,@args) = @_;
 243    $self->throw_not_implemented();
 244 }
 245
 246
 247 =head2 Bio::Event::EventHandlerI methods
 248
 249 =cut
 250
 251 =head2 will_handle
 252
 253  Title   : will_handle
 254  Usage   : if( $handler->will_handle($event_type) ) { ... }
 255  Function: Tests if this event builder knows how to process a specific event
 256  Returns : boolean
 257  Args    : event type name
 258
 259
 260 =cut
 261
 262 =head2 SAX methods
 263
 264 See L<Bio::Event::EventHandlerI> for the additional SAX methods.
 265
 266 =cut
 267
 268
 269 1;