File Coverage

Bio/Event/EventHandlerI.pm
Criterion Covered Total %
statement 9 25 36.0
branch n/a
condition n/a
subroutine 3 11 27.2
pod 8 8 100.0
total 20 44 45.4


line stmt bran cond sub pod time code
1             #
2             # BioPerl module for Bio::Event::EventHandlerI
3             #
4             # Please direct questions and support issues to
5             #
6             # Cared for by Jason Stajich
7             #
8             # Copyright Jason Stajich
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::Event::EventHandlerI - An Event Handler Interface
17              
18             =head1 SYNOPSIS
19              
20             # do not use this module directly
21             # See Bio::SearchIO::SearchResultEventHandler for an example of
22             # implementation.
23              
24             =head1 DESCRIPTION
25              
26             This interface describes the basic methods required for
27             EventHandlers. These are essentially SAX methods.
28              
29             =head1 Developer Notes
30              
31             EventHandlerI implementations are used in the BioPerl IO systems to
32             decouple the task of tokenizing the input stream into data elements
33             and their attributes, which is format-specific, and the task of
34             collecting those elements and attributes into whatever is the result
35             of a parser, which is specific to the kind of result to be produced,
36             such as BioPerl objects, a tabular or array data structure, etc.
37              
38             You can think of EventHandlerI-compliant parsers as faking a SAX XML
39             parser, making their input (typically a non-XML document) behave as if
40             it were XML. The overhead to do this can be quite substantial, at the
41             gain of not having to duplicate the parsing code in order to change
42             the parsing result, and not having to duplicate the logic of
43             instantiating objects between parsers for different formats that all
44             give rise to the same types of objects. This is perhaps best
45             illustrated by the Bio::SearchIO system, where many different formats
46             exist for sequence similarity and pairwise sequence alignment exist
47             that essentially all result in Bio::Search objects.
48              
49             The method names and their invocation semantics follow their XML SAX
50             equivalents, see http://www.saxproject.org/apidoc/, especially the
51             org.xml.sax.ContentHandler interface.
52              
53             =head1 FEEDBACK
54              
55             =head2 Mailing Lists
56              
57             User feedback is an integral part of the evolution of this and other
58             Bioperl modules. Send your comments and suggestions preferably to
59             the Bioperl mailing list. Your participation is much appreciated.
60              
61             bioperl-l@bioperl.org - General discussion
62             http://bioperl.org/wiki/Mailing_lists - About the mailing lists
63              
64             =head2 Support
65              
66             Please direct usage questions or support issues to the mailing list:
67              
68             I
69              
70             rather than to the module maintainer directly. Many experienced and
71             reponsive experts will be able look at the problem and quickly
72             address it. Please include a thorough description of the problem
73             with code and data examples if at all possible.
74              
75             =head2 Reporting Bugs
76              
77             Report bugs to the Bioperl bug tracking system to help us keep track
78             of the bugs and their resolution. Bug reports can be submitted via the
79             web:
80              
81             https://github.com/bioperl/bioperl-live/issues
82              
83             =head1 AUTHOR - Jason Stajich
84              
85             Email jason@bioperl.org
86              
87             =head1 APPENDIX
88              
89             The rest of the documentation details each of the object methods.
90             Internal methods are usually preceded with a _
91              
92             =cut
93              
94              
95             # Let the code begin...
96              
97              
98             package Bio::Event::EventHandlerI;
99 53     53   245 use strict;
  53         57  
  53         1169  
100 53     53   161 use Carp;
  53         56  
  53         2480  
101              
102 53     53   179 use base qw(Bio::Root::RootI);
  53         58  
  53         11961  
103              
104             =head2 will_handle
105              
106             Title : will_handle
107             Usage : if( $handler->will_handle($event_type) ) { ... }
108             Function: Tests if this event builder knows how to process a specific event
109             Returns : boolean
110             Args : event type name
111              
112              
113             =cut
114              
115             sub will_handle{
116 0     0 1   my ($self,$type) = @_;
117 0           $self->throw_not_implemented();
118             }
119              
120             =head2 SAX methods
121              
122             =cut
123              
124             =head2 start_document
125              
126             Title : start_document
127             Usage : $resultObj = $parser->start_document();
128             Function: Receive notification of the beginning of a document (the
129             input file of a parser). The parser will invoke this method
130             only once, before any other event callbacks.
131              
132             Usually, a handler will reset any internal state structures
133             when this method is called.
134              
135             Returns : none
136             Args : none
137              
138              
139             =cut
140              
141             sub start_document{
142 0     0 1   my ($self,@args) = @_;
143 0           $self->throw_not_implemented;
144             }
145              
146             =head2 end_document
147              
148             Title : end_document
149             Usage : $parser->end_document();
150             Function: Receive notification of the end of a document (normally the
151             input file of a parser). The parser will invoke this method
152             only once, and it will be the last method invoked during
153             the parse of the document. The parser shall not invoke this
154             method until it has either abandoned parsing (because of an
155             unrecoverable error) or reached the end of input.
156              
157             Unlike the XML SAX signature of this method, this method is
158             expected to return the object representing the result of
159             parsing the document.
160              
161             Returns : The object representing the result of parsing the input
162             stream between the calls to start_document() and this method.
163             Args : none
164              
165              
166             =cut
167              
168             sub end_document{
169 0     0 1   my ($self,@args) = @_;
170 0           $self->throw_not_implemented;
171             }
172              
173             =head2 start_element
174              
175             Title : start_element
176             Usage : $parser->start_element
177              
178             Function: Receive notification of the beginning of an element. The
179             Parser will invoke this method at the beginning of every
180             element in the input stream; there will be a corresponding
181             end_element() event for every start_element() event (even when
182             the element is empty). All of the element's content will be
183             reported, in order, before the corresponding end_element()
184             event.
185              
186             Returns : none
187             Args : A hashref with at least 2 keys: 'Data' and 'Name'. The value
188             for 'Name' is expected to be the type of element being
189             encountered; the understood values will depend on the IO
190             parser to which this interface is being applied. Likewise, the
191             value for 'Data' will be specific to event handler
192             implementions, and the specific data chunking needs of input
193             formats to be handled efficiently.
194              
195              
196             =cut
197              
198             sub start_element{
199 0     0 1   my ($self,@args) = @_;
200 0           $self->throw_not_implemented;
201             }
202              
203             =head2 end_element
204              
205             Title : end_element
206             Usage : $parser->end_element
207              
208             Function: Receive notification of the end of an element. The parser
209             will invoke this method at the end of every element in the
210             input stream; there will be a corresponding start_element()
211             event for every end_element() event (even when the element
212             is empty).
213              
214             Returns : none
215              
216             Args : hashref with at least 2 keys, 'Data' and 'Name'. The semantics
217             are the same as for start_element().
218              
219              
220             =cut
221              
222             sub end_element{
223 0     0 1   my ($self,@args) = @_;
224 0           $self->throw_not_implemented;
225             }
226              
227              
228             =head2 in_element
229              
230             Title : in_element
231             Usage : if( $handler->in_element($element) ) {}
232              
233             Function: Test if we are in a particular element.
234              
235             Normally, in_element() will test for particular attributes,
236             or nested elements, within a containing
237             element. Conversely, the containing element can be queries
238             with within_element(). The names understood as argument
239             should be the same as the ones understood for the 'Name'
240             key in start_element() and end_element().
241              
242             Typically, handler implementations will call this method
243             from within the characters() method to determine the
244             context of the data that were passed to characters().
245              
246             Returns : boolean
247              
248             Args : A string, the name of the element (normally an attribute name or nested sub-element name).
249              
250             =cut
251              
252             sub in_element{
253 0     0 1   my ($self,@args) = @_;
254 0           $self->throw_not_implemented;
255              
256             }
257              
258             =head2 within_element
259              
260             Title : within_element
261             Usage : if( $handler->within_element($element) ) {}
262              
263             Function: Test if we are within a particular kind of element.
264              
265             Normally, the element type names understood as argument
266             values will be for containing elements or data
267             chunks. Conversely, in_element() can be used to test
268             whether an attribute or nested element is the ccurrent
269             context.
270              
271             Typically, a handler will call this method from within the
272             characters() method to determine the context for the data
273             that were passed to characters().
274              
275             Returns : boolean
276             Args : string element name
277              
278              
279             =cut
280              
281             sub within_element{
282 0     0 1   my ($self,@args) = @_;
283 0           $self->throw_not_implemented;
284             }
285              
286             =head2 characters
287              
288             Title : characters
289             Usage : $parser->characters($str)
290             Function: Receive notification of character data. The parser will
291             call this method to report values of attributes, or larger
292             data chunks, depending on the IO subsystem and event
293             handler implementation. Values may be whitespace-padded
294             even if the whitespace is insignificant for the format.
295              
296             The context of the character data being passed can be
297             determined by calling the in_element() and within_element()
298             methods.
299              
300             Returns : none
301             Args : string, the character data
302              
303              
304             =cut
305              
306             sub characters{
307 0     0 1   my ($self,@args) = @_;
308 0           $self->throw_not_implemented;
309             }
310              
311             1;