Bio/HandlerBaseI.pm

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