File Coverage

Bio/HandlerBaseI.pm
Criterion Covered Total %
statement 9 15 60.0
branch n/a
condition n/a
subroutine 3 9 33.3
pod 6 6 100.0
total 18 30 60.0


line stmt bran cond sub pod time code
1             #
2             # BioPerl module for Bio::HandlerI
3             #
4             # Please direct questions and support issues to
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
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 4     4   21 use strict;
  4         4  
  4         93  
138 4     4   14 use warnings;
  4         5  
  4         97  
139              
140 4     4   16 use base qw(Bio::Root::RootI);
  4         5  
  4         682  
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 0     0 1   }
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 0     0 1   }
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 0     0 1   }
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 0     0 1   }
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 0     0 1   }
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 0     0 1   }
249              
250             1;
251