1
# $Id: HandlerBaseI.pm 15060 2008-12-02 13:40:53Z cjfields $
3
# BioPerl module for Bio::HandlerI
5
# Cared for by Chris Fields
7
# Copyright Chris Fields
9
# You may distribute this module under the same terms as perl itself
11
# POD documentation - main docs before the code
15
Bio::HandlerBaseI - Interface class for handler methods which interact with any
16
event-driven parsers (drivers).
20
# MyHandler is a Bio::HandlerBaseI-derived class for dealing with GenBank
21
# sequence data, derived from a GenBank event-driven parser
23
# inside a parser (driver) constructor
25
$self->seqhandler($handler || MyHandler->new(-format => 'genbank'));
27
# in the driver parsing method ( such as next_seq() ) ...
29
$handler = $self->seqhandler();
31
# roll data up into hashref chunks, pass off into Handler for processing...
33
$hobj->data_handler($data);
35
# or retrieve Handler methods and pass data directly to Handler methods
37
my $hmeth = $hobj->handler_methods;
39
if ($hmeth->{ $data->{NAME} }) {
40
my $mth = $hmeth->{ $data->{NAME} }; # code ref
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):
54
Annotation Data (References):
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)'
64
Sequence features (source seqfeature):
67
'mol_type' => 'genomic DNA',
68
'LOCATION' => '<1..>10001',
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'
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).
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).
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.
100
bioperl-l@bioperl.org - General discussion
101
http://bioperl.org/wiki/Mailing_lists - About the mailing lists
103
=head2 Reporting Bugs
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
109
http://bugzilla.open-bio.org/
111
=head1 AUTHOR - Chris Fields
113
Email cjfields at uiuc dot edu
117
The rest of the documentation details each of the object methods. Internal
118
methods are usually preceded with a _
122
# Let the code begin...
124
package Bio::HandlerBaseI;
128
use base qw(Bio::Root::RootI);
130
my %HANDLERS = ('foo' => \&noop);
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.
142
Args : an hash ref containing a data chunk.
147
shift->throw_not_implemented
150
=head2 handler_methods
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
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
166
sub handler_methods {
167
shift->throw_not_implemented
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)
186
shift->throw_not_implemented
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
203
shift->throw_not_implemented
209
Usage : $handler->set_params({
210
'-species' => $species,
211
'-accession_number' => $acc
213
Function: Convenience method used to set specific parameters
215
Args : Hash ref containing the data to be passed as key-value pairs
220
shift->throw_not_implemented
223
=head2 reset_parameters
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)
234
sub reset_parameters {
235
shift->throw_not_implemented
added
removed
Bio/HandlerBaseI.pm
