3 # BioPerl module for Bio::HandlerI
5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
7 # Cared for by Chris Fields
9 # Copyright Chris Fields
11 # You may distribute this module under the same terms as perl itself
13 # POD documentation - main docs before the code
17 Bio::HandlerBaseI - Interface class for handler methods which interact with any
18 event-driven parsers (drivers).
22 # MyHandler is a Bio::HandlerBaseI-derived class for dealing with GenBank
23 # sequence data, derived from a GenBank event-driven parser
25 # inside a parser (driver) constructor
27 $self->seqhandler($handler || MyHandler->new(-format => 'genbank'));
29 # in the driver parsing method ( such as next_seq() ) ...
31 $handler = $self->seqhandler();
33 # roll data up into hashref chunks, pass off into Handler for processing...
35 $hobj->data_handler($data);
37 # or retrieve Handler methods and pass data directly to Handler methods
39 my $hmeth = $hobj->handler_methods;
41 if ($hmeth->{ $data->{NAME} }) {
42 my $mth = $hmeth->{ $data->{NAME} }; # code ref
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):
56 Annotation Data (References):
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)'
66 Sequence features (source seqfeature):
69 'mol_type' => 'genomic DNA',
70 'LOCATION' => '<1..>10001',
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'
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).
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).
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.
102 bioperl-l@bioperl.org - General discussion
103 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
107 Please direct usage questions or support issues to the mailing list:
109 I<bioperl-l@bioperl.org>
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.
116 =head2 Reporting Bugs
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
122 http://bugzilla.open-bio.org/
124 =head1 AUTHOR - Chris Fields
126 Email cjfields at bioperl dot org
130 The rest of the documentation details each of the object methods. Internal
131 methods are usually preceded with a _
135 # Let the code begin...
137 package Bio
::HandlerBaseI
;
141 use base
qw(Bio::Root::RootI);
143 my %HANDLERS = ('foo' => \
&noop
);
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.
155 Args : an hash ref containing a data chunk.
160 shift->throw_not_implemented
163 =head2 handler_methods
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
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
179 sub handler_methods
{
180 shift->throw_not_implemented
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)
199 shift->throw_not_implemented
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
216 shift->throw_not_implemented
222 Usage : $handler->set_params({
223 '-species' => $species,
224 '-accession_number' => $acc
226 Function: Convenience method used to set specific parameters
228 Args : Hash ref containing the data to be passed as key-value pairs
233 shift->throw_not_implemented
236 =head2 reset_parameters
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)
247 sub reset_parameters
{
248 shift->throw_not_implemented