Bio/Event/EventHandlerI.pm

filter: Statementstmt 40.7% 11 / 27 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 27.2% 3 / 11 Podpod 100% 8 / 8 totaltotal 47.8% 22 / 46 CC 1 SCAR 5.5
CC
1
Cov
41%
will_handle
2.0
start_document
2.0
end_document
2.0
CRAP 1.7
« Bio/Factory/DriverFactory.pm ↑ Summary Bio/Matrix/PSM/InstanceSiteI.pm »
1 #
2 # BioPerl module for Bio::Event::EventHandlerI
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Jason Stajich <jason@bioperl.org>
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<bioperl-l@bioperl.org>
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 81 $Bio::Event::EventHandlerI::VERSION = '1.7.8';
100 81 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
101 81 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
102  
103 81 ▶use base qw(Bio::Root::RootI);
Subroutine BEGIN: called CC=1 SCAR=0.0
104  
105 =head2 will_handle
106  
107 Title : will_handle
108 Usage : if( $handler->will_handle($event_type) ) { ... }
109 Function: Tests if this event builder knows how to process a specific event
110 Returns : boolean
111 Args : event type name
112  
113  
114 =cut
115  
116 0 ▶sub will_handle{
Subroutine will_handle: not called CC=1 SCAR=6.9
Pod documented
117 0 my ($self,$type) = @_;
118 0 $self->throw_not_implemented();
119 }
120  
121 =head2 SAX methods
122  
123 =cut
124  
125 =head2 start_document
126  
127 Title : start_document
128 Usage : $resultObj = $parser->start_document();
129 Function: Receive notification of the beginning of a document (the
130 input file of a parser). The parser will invoke this method
131 only once, before any other event callbacks.
132  
133 Usually, a handler will reset any internal state structures
134 when this method is called.
135  
136 Returns : none
137 Args : none
138  
139  
140 =cut
141  
142 0 ▶sub start_document{
Subroutine start_document: not called CC=1 SCAR=6.9
Pod documented
143 0 my ($self,@args) = @_;
144 0 $self->throw_not_implemented;
145 }
146  
147 =head2 end_document
148  
149 Title : end_document
150 Usage : $parser->end_document();
151 Function: Receive notification of the end of a document (normally the
152 input file of a parser). The parser will invoke this method
153 only once, and it will be the last method invoked during
154 the parse of the document. The parser shall not invoke this
155 method until it has either abandoned parsing (because of an
156 unrecoverable error) or reached the end of input.
157  
158 Unlike the XML SAX signature of this method, this method is
159 expected to return the object representing the result of
160 parsing the document.
161  
162 Returns : The object representing the result of parsing the input
163 stream between the calls to start_document() and this method.
164 Args : none
165  
166  
167 =cut
168  
169 0 ▶sub end_document{
Subroutine end_document: not called CC=1 SCAR=6.9
Pod documented
170 0 my ($self,@args) = @_;
171 0 $self->throw_not_implemented;
172 }
173  
174 =head2 start_element
175  
176 Title : start_element
177 Usage : $parser->start_element
178  
179 Function: Receive notification of the beginning of an element. The
180 Parser will invoke this method at the beginning of every
181 element in the input stream; there will be a corresponding
182 end_element() event for every start_element() event (even when
183 the element is empty). All of the element's content will be
184 reported, in order, before the corresponding end_element()
185 event.
186  
187 Returns : none
188 Args : A hashref with at least 2 keys: 'Data' and 'Name'. The value
189 for 'Name' is expected to be the type of element being
190 encountered; the understood values will depend on the IO
191 parser to which this interface is being applied. Likewise, the
192 value for 'Data' will be specific to event handler
193 implementions, and the specific data chunking needs of input
194 formats to be handled efficiently.
195  
196  
197 =cut
198  
199 0 ▶sub start_element{
Subroutine start_element: not called CC=1 SCAR=6.9
Pod documented
200 0 my ($self,@args) = @_;
201 0 $self->throw_not_implemented;
202 }
203  
204 =head2 end_element
205  
206 Title : end_element
207 Usage : $parser->end_element
208  
209 Function: Receive notification of the end of an element. The parser
210 will invoke this method at the end of every element in the
211 input stream; there will be a corresponding start_element()
212 event for every end_element() event (even when the element
213 is empty).
214  
215 Returns : none
216  
217 Args : hashref with at least 2 keys, 'Data' and 'Name'. The semantics
218 are the same as for start_element().
219  
220  
221 =cut
222  
223 0 ▶sub end_element{
Subroutine end_element: not called CC=1 SCAR=6.9
Pod documented
224 0 my ($self,@args) = @_;
225 0 $self->throw_not_implemented;
226 }
227  
228  
229 =head2 in_element
230  
231 Title : in_element
232 Usage : if( $handler->in_element($element) ) {}
233  
234 Function: Test if we are in a particular element.
235  
236 Normally, in_element() will test for particular attributes,
237 or nested elements, within a containing
238 element. Conversely, the containing element can be queries
239 with within_element(). The names understood as argument
240 should be the same as the ones understood for the 'Name'
241 key in start_element() and end_element().
242  
243 Typically, handler implementations will call this method
244 from within the characters() method to determine the
245 context of the data that were passed to characters().
246  
247 Returns : boolean
248  
249 Args : A string, the name of the element (normally an attribute name or nested sub-element name).
250  
251 =cut
252  
253 0 ▶sub in_element{
Subroutine in_element: not called CC=1 SCAR=6.9
Pod documented
254 0 my ($self,@args) = @_;
255 0 $self->throw_not_implemented;
256  
257 }
258  
259 =head2 within_element
260  
261 Title : within_element
262 Usage : if( $handler->within_element($element) ) {}
263  
264 Function: Test if we are within a particular kind of element.
265  
266 Normally, the element type names understood as argument
267 values will be for containing elements or data
268 chunks. Conversely, in_element() can be used to test
269 whether an attribute or nested element is the ccurrent
270 context.
271  
272 Typically, a handler will call this method from within the
273 characters() method to determine the context for the data
274 that were passed to characters().
275  
276 Returns : boolean
277 Args : string element name
278  
279  
280 =cut
281  
282 0 ▶sub within_element{
Subroutine within_element: not called CC=1 SCAR=6.9
Pod documented
283 0 my ($self,@args) = @_;
284 0 $self->throw_not_implemented;
285 }
286  
287 =head2 characters
288  
289 Title : characters
290 Usage : $parser->characters($str)
291 Function: Receive notification of character data. The parser will
292 call this method to report values of attributes, or larger
293 data chunks, depending on the IO subsystem and event
294 handler implementation. Values may be whitespace-padded
295 even if the whitespace is insignificant for the format.
296  
297 The context of the character data being passed can be
298 determined by calling the in_element() and within_element()
299 methods.
300  
301 Returns : none
302 Args : string, the character data
303  
304  
305 =cut
306  
307 0 ▶sub characters{
Subroutine characters: not called CC=1 SCAR=6.9
Pod documented
308 0 my ($self,@args) = @_;
309 0 $self->throw_not_implemented;
310 }
311  
312 81 1;
« Bio/Factory/DriverFactory.pm ↑ Summary Bio/Matrix/PSM/InstanceSiteI.pm »