| 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 | 7 | $Bio::HandlerBaseI::VERSION = '1.7.8'; | |
| 138 | 7 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 139 | 7 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 140 | |||
| 141 | 7 | ▶ | use base qw(Bio::Root::RootI); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 142 | |||
| 143 | 7 | my %HANDLERS = ('foo' => \&noop); | |
| 144 | |||
| 145 | =head2 data_handler | ||
| 146 | |||
| 147 | Title : data_handler | ||
| 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. | ||
| 152 | |||
| 153 | One can also use | ||
| 154 | Returns : None | ||
| 155 | Args : an hash ref containing a data chunk. | ||
| 156 | |||
| 157 | =cut | ||
| 158 | |||
| 159 | 0 | ▶ | sub data_handler { |
|
Subroutine
data_handler: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 160 | shift->throw_not_implemented | ||
| 161 | 0 | } | |
| 162 | |||
| 163 | =head2 handler_methods | ||
| 164 | |||
| 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 | ||
| 172 | associated with it. | ||
| 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 | ||
| 176 | |||
| 177 | =cut | ||
| 178 | |||
| 179 | 0 | ▶ | sub handler_methods { |
|
Subroutine
handler_methods: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 180 | shift->throw_not_implemented | ||
| 181 | 0 | } | |
| 182 | |||
| 183 | =head2 format | ||
| 184 | |||
| 185 | Title : format | ||
| 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) | ||
| 195 | |||
| 196 | =cut | ||
| 197 | |||
| 198 | 0 | ▶ | sub format { |
|
Subroutine
format: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 199 | shift->throw_not_implemented | ||
| 200 | 0 | } | |
| 201 | |||
| 202 | =head2 get_params | ||
| 203 | |||
| 204 | Title : get_params | ||
| 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 | ||
| 212 | |||
| 213 | =cut | ||
| 214 | |||
| 215 | 0 | ▶ | sub get_params { |
|
Subroutine
get_params: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 216 | shift->throw_not_implemented | ||
| 217 | 0 | } | |
| 218 | |||
| 219 | =head2 set_params | ||
| 220 | |||
| 221 | Title : set_params | ||
| 222 | Usage : $handler->set_params({ | ||
| 223 | '-species' => $species, | ||
| 224 | '-accession_number' => $acc | ||
| 225 | }); | ||
| 226 | Function: Convenience method used to set specific parameters | ||
| 227 | Returns : None | ||
| 228 | Args : Hash ref containing the data to be passed as key-value pairs | ||
| 229 | |||
| 230 | =cut | ||
| 231 | |||
| 232 | 0 | ▶ | sub set_params { |
|
Subroutine
set_params: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 233 | shift->throw_not_implemented | ||
| 234 | 0 | } | |
| 235 | |||
| 236 | =head2 reset_parameters | ||
| 237 | |||
| 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) | ||
| 242 | Returns : None | ||
| 243 | Args : None | ||
| 244 | |||
| 245 | =cut | ||
| 246 | |||
| 247 | 0 | ▶ | sub reset_parameters { |
|
Subroutine
reset_parameters: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 248 | shift->throw_not_implemented | ||
| 249 | 0 | } | |
| 250 | |||
| 251 | 7 | 1; | |
| 252 | |||