Bio/HandlerBaseI.pm

   1 #
   2 # BioPerl module for Bio::HandlerI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Chris Fields
   7 #
   8 # Copyright Chris Fields
   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::HandlerBaseI - Interface class for handler methods which interact with any
  17 event-driven parsers (drivers).
  18
  19 =head1 SYNOPSIS
  20
  21   # MyHandler is a Bio::HandlerBaseI-derived class for dealing with GenBank
  22   # sequence data, derived from a GenBank event-driven parser
  23
  24   # inside a parser (driver) constructor
  25
  26   $self->seqhandler($handler || MyHandler->new(-format => 'genbank'));
  27
  28   # in the driver parsing method ( such as next_seq() ) ...
  29
  30   $handler = $self->seqhandler();
  31
  32   # roll data up into hashref chunks, pass off into Handler for processing...
  33
  34   $hobj->data_handler($data);
  35
  36   # or retrieve Handler methods and pass data directly to Handler methods
  37
  38   my $hmeth = $hobj->handler_methods;
  39
  40   if ($hmeth->{ $data->{NAME} }) {
  41       my $mth = $hmeth->{ $data->{NAME} }; # code ref
  42       $hobj->$mth($data);
  43   }
  44
  45 =head1 DESCRIPTION
  46
  47 This interface describes simple class methods used for processing data from an
  48 event-based parser (a driver). This is similar in theme to an XML SAX-based
  49 driver but differs in that one can optionally pass related data
  50 semi-intelligently as chunks (defined in a hash reference) vs. passing as single
  51 data elements in a stream. For instance, any reference-related and
  52 species-related data as well as individual sequence features could be passed as
  53 chunks of data to be 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 Support
 105
 106 Please direct usage questions or support issues to the mailing list:
 107
 108 I<bioperl-l@bioperl.org>
 109
 110 rather than to the module maintainer directly. Many experienced and
 111 reponsive experts will be able look at the problem and quickly
 112 address it. Please include a thorough description of the problem
 113 with code and data examples if at all possible.
 114
 115 =head2 Reporting Bugs
 116
 117 Report bugs to the Bioperl bug tracking system to help us keep track
 118 the bugs and their resolution.  Bug reports can be submitted via the
 119 web:
 120
 121   https://github.com/bioperl/bioperl-live/issues
 122
 123 =head1 AUTHOR - Chris Fields
 124
 125 Email cjfields at bioperl dot org
 126
 127 =head1 APPENDIX
 128
 129 The rest of the documentation details each of the object methods. Internal
 130 methods are usually preceded with a _
 131
 132 =cut
 133
 134 # Let the code begin...
 135
 136 package Bio::HandlerBaseI;
 137 use strict;
 138 use warnings;
 139
 140 use base qw(Bio::Root::RootI);
 141
 142 my %HANDLERS = ('foo' => \&noop);
 143
 144 =head2 data_handler
 145
 146  Title   :  data_handler
 147  Usage   :  $handler->data_handler($data)
 148  Function:  Centralized method which accepts all data chunks, then distributes
 149             to the appropriate methods for processing based on the chunk name
 150             from within the HandlerBaseI object.
 151
 152             One can also use
 153  Returns :  None
 154  Args    :  an hash ref containing a data chunk.
 155
 156 =cut
 157
 158 sub data_handler {
 159     shift->throw_not_implemented
 160 }
 161
 162 =head2 handler_methods
 163
 164  Title   :  handler_methods
 165  Usage   :  $handler->handler_methods('GenBank')
 166             %handlers = $handler->handler_methods();
 167  Function:  Retrieve the handler methods used for the current format() in
 168             the handler.  This assumes the handler methods are already
 169             described in the HandlerI-implementing class.
 170  Returns :  a hash reference with the data type handled and the code ref
 171             associated with it.
 172  Args    :  [optional] String representing the sequence format.  If set here
 173             this will also set sequence_format()
 174  Throws  :  On unimplemented sequence format in %HANDLERS
 175
 176 =cut
 177
 178 sub handler_methods {
 179     shift->throw_not_implemented
 180 }
 181
 182 =head2 format
 183
 184  Title   :  format
 185  Usage   :  $handler->format('GenBank')
 186             $handler->format('BLAST')
 187  Function:  Get/Set the format for the report/record being parsed. This can be
 188             used to set handlers in classes which are capable of processing
 189             similar data chunks from multiple driver modules.
 190  Returns :  String with the sequence format
 191  Args    :  [optional] String with the sequence format
 192  Note    :  The format may be used to set the handlers (as in the
 193             current GenericRichSeqHandler implementation)
 194
 195 =cut
 196
 197 sub format {
 198     shift->throw_not_implemented
 199 }
 200
 201 =head2 get_params
 202
 203  Title   :  get_params
 204  Usage   :  $handler->get_params('-species')
 205  Function:  Convenience method used to retrieve the specified
 206             parameters from the internal parameter cache
 207  Returns :  Hash ref containing parameters requested and data as
 208             key-value pairs.  Note that some parameter values may be
 209             objects, arrays, etc.
 210  Args    :  List (array) representing the parameters requested
 211
 212 =cut
 213
 214 sub get_params {
 215     shift->throw_not_implemented
 216 }
 217
 218 =head2 set_params
 219
 220  Title   :  set_params
 221  Usage   :  $handler->set_params({
 222                                 '-species' => $species,
 223                                 '-accession_number' => $acc
 224                                 });
 225  Function:  Convenience method used to set specific parameters
 226  Returns :  None
 227  Args    :  Hash ref containing the data to be passed as key-value pairs
 228
 229 =cut
 230
 231 sub set_params {
 232     shift->throw_not_implemented
 233 }
 234
 235 =head2 reset_parameters
 236
 237  Title   :  reset_parameters
 238  Usage   :  $handler->reset_parameters()
 239  Function:  Resets the internal cache of data (normally object parameters for
 240             a builder or factory)
 241  Returns :  None
 242  Args    :  None
 243
 244 =cut
 245
 246 sub reset_parameters {
 247     shift->throw_not_implemented
 248 }
 249
 250 1;
 251