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