Bio/HandlerBaseI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::HandlerI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Chris Fields
   8 #
   9 # Copyright Chris Fields
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::HandlerBaseI - Interface class for handler methods which interact with any
  18 event-driven parsers (drivers).
  19
  20 =head1 SYNOPSIS
  21
  22   # MyHandler is a Bio::HandlerBaseI-derived class for dealing with GenBank
  23   # sequence data, derived from a GenBank event-driven parser
  24
  25   # inside a parser (driver) constructor
  26
  27   $self->seqhandler($handler || MyHandler->new(-format => 'genbank'));
  28
  29   # in the driver parsing method ( such as next_seq() ) ...
  30
  31   $handler = $self->seqhandler();
  32
  33   # roll data up into hashref chunks, pass off into Handler for processing...
  34
  35   $hobj->data_handler($data);
  36
  37   # or retrieve Handler methods and pass data directly to Handler methods
  38
  39   my $hmeth = $hobj->handler_methods;
  40
  41   if ($hmeth->{ $data->{NAME} }) {
  42       my $mth = $hmeth->{ $data->{NAME} }; # code ref
  43       $hobj->$mth($data);
  44   }
  45
  46 =head1 DESCRIPTION
  47
  48 This interface describes simple class methods used for processing data from an
  49 event-based parser (a driver). This is similar in theme to an XML SAX-based
  50 driver but differs in that one can optionally pass related data
  51 semi-intelligently as chunks (defined in a hash reference) vs. passing as single
  52 data elements in a stream. For instance, any reference-related and
  53 species-related data as well as individual sequence features could be passed as
  54 chunks of data to be processed in part or as a whole (from Data::Dumper output):
  55
  56 Annotation Data (References):
  57
  58   $VAR1 = {
  59           'NAME' => 'REFERENCE',
  60           'DATA' => '1  (bases 1 to 10001)'
  61           'AUTHORS' => 'International Human Genome Sequencing Consortium.'
  62           'TITLE' => 'The DNA sequence of Homo sapiens'
  63           'JOURNAL' => 'Unpublished (2003)'
  64           };
  65
  66 Sequence features (source seqfeature):
  67
  68   $VAR1 = {
  69           'mol_type' => 'genomic DNA',
  70           'LOCATION' => '<1..>10001',
  71           'NAME' => 'FEATURES',
  72           'FEATURE_KEY' => 'source',
  73           'note' => 'Accession AL451081 sequenced by The Sanger Centre',
  74           'db_xref' => 'taxon:9606',
  75           'clone' => 'RP11-302I18',
  76           'organism' => 'Homo sapiens'
  77           };
  78
  79 These would be 'handled' accordingly by methods specified in a
  80 HandlerI-based class. The data in a chunk is intentionally left vague
  81 here since this may vary from implementation to implementation and can
  82 be somewhat open to interpretation. A data chunk in a sequence record,
  83 for instance, will be different than a data chunk in a BLAST
  84 report. This also allows one the flexibility to pass data as more
  85 XML-like small bits, as huge chunks, or even as indexed locations in a
  86 file (such as when using a "pull" parser, like a Bio::PullParserI).
  87
  88 For an sequence-based implementation see
  89 Bio::SeqIO::RichSeq::GenericRichSeqHandler, which handles any GenBank,
  90 UniProt, and EMBL data from their respective driver modules
  91 (Bio::SeqIO::gbdriver, Bio::SeqIO::swissdriver, and
  92 Bio::SeqIO::embldriver).
  93
  94 =head1 FEEDBACK
  95
  96 =head2 Mailing Lists
  97
  98 User feedback is an integral part of the evolution of this and other
  99 Bioperl modules. Send your comments and suggestions preferably to one
 100 of the Bioperl mailing lists.  Your participation is much appreciated.
 101
 102   bioperl-l@bioperl.org                  - General discussion
 103   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 104
 105 =head2 Support
 106
 107 Please direct usage questions or support issues to the mailing list:
 108
 109 L<bioperl-l@bioperl.org>
 110
 111 rather than to the module maintainer directly. Many experienced and
 112 reponsive experts will be able look at the problem and quickly
 113 address it. Please include a thorough description of the problem
 114 with code and data examples if at all possible.
 115
 116 =head2 Reporting Bugs
 117
 118 Report bugs to the Bioperl bug tracking system to help us keep track
 119 the bugs and their resolution.  Bug reports can be submitted via the
 120 web:
 121
 122   http://bugzilla.open-bio.org/
 123
 124 =head1 AUTHOR - Chris Fields
 125
 126 Email cjfields at bioperl dot org
 127
 128 =head1 APPENDIX
 129
 130 The rest of the documentation details each of the object methods. Internal
 131 methods are usually preceded with a _
 132
 133 =cut
 134
 135 # Let the code begin...
 136
 137 package Bio::HandlerBaseI;
 138 use strict;
 139 use warnings;
 140
 141 use base qw(Bio::Root::RootI);
 142
 143 my %HANDLERS = ('foo' => \&noop);
 144
 145 =head2 data_handler
 146
 147  Title   :  data_handler
 148  Usage   :  $handler->data_handler($data)
 149  Function:  Centralized method which accepts all data chunks, then distributes
 150             to the appropriate methods for processing based on the chunk name
 151             from within the HandlerBaseI object.
 152
 153             One can also use
 154  Returns :  None
 155  Args    :  an hash ref containing a data chunk.
 156
 157 =cut
 158
 159 sub data_handler {
 160     shift->throw_not_implemented
 161 }
 162
 163 =head2 handler_methods
 164
 165  Title   :  handler_methods
 166  Usage   :  $handler->handler_methods('GenBank')
 167             %handlers = $handler->handler_methods();
 168  Function:  Retrieve the handler methods used for the current format() in
 169             the handler.  This assumes the handler methods are already
 170             described in the HandlerI-implementing class.
 171  Returns :  a hash reference with the data type handled and the code ref
 172             associated with it.
 173  Args    :  [optional] String representing the sequence format.  If set here
 174             this will also set sequence_format()
 175  Throws  :  On unimplemented sequence format in %HANDLERS
 176
 177 =cut
 178
 179 sub handler_methods {
 180     shift->throw_not_implemented
 181 }
 182
 183 =head2 format
 184
 185  Title   :  format
 186  Usage   :  $handler->format('GenBank')
 187             $handler->format('BLAST')
 188  Function:  Get/Set the format for the report/record being parsed. This can be
 189             used to set handlers in classes which are capable of processing
 190             similar data chunks from multiple driver modules.
 191  Returns :  String with the sequence format
 192  Args    :  [optional] String with the sequence format
 193  Note    :  The format may be used to set the handlers (as in the
 194             current GenericRichSeqHandler implementation)
 195
 196 =cut
 197
 198 sub format {
 199     shift->throw_not_implemented
 200 }
 201
 202 =head2 get_params
 203
 204  Title   :  get_params
 205  Usage   :  $handler->get_params('-species')
 206  Function:  Convenience method used to retrieve the specified
 207             parameters from the internal parameter cache
 208  Returns :  Hash ref containing parameters requested and data as
 209             key-value pairs.  Note that some parameter values may be
 210             objects, arrays, etc.
 211  Args    :  List (array) representing the parameters requested
 212
 213 =cut
 214
 215 sub get_params {
 216     shift->throw_not_implemented
 217 }
 218
 219 =head2 set_params
 220
 221  Title   :  set_params
 222  Usage   :  $handler->set_params({
 223                                 '-species' => $species,
 224                                 '-accession_number' => $acc
 225                                 });
 226  Function:  Convenience method used to set specific parameters
 227  Returns :  None
 228  Args    :  Hash ref containing the data to be passed as key-value pairs
 229
 230 =cut
 231
 232 sub set_params {
 233     shift->throw_not_implemented
 234 }
 235
 236 =head2 reset_parameters
 237
 238  Title   :  reset_parameters
 239  Usage   :  $handler->reset_parameters()
 240  Function:  Resets the internal cache of data (normally object parameters for
 241             a builder or factory)
 242  Returns :  None
 243  Args    :  None
 244
 245 =cut
 246
 247 sub reset_parameters {
 248     shift->throw_not_implemented
 249 }
 250
 251 1;
 252