2 # BioPerl module for Bio::Event::EventHandlerI
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Jason Stajich <jason@bioperl.org>
8 # Copyright Jason Stajich
10 # You may distribute this module under the same terms as perl itself
12 # POD documentation - main docs before the code
16 Bio::Event::EventHandlerI - An Event Handler Interface
20 # do not use this module directly
21 # See Bio::SearchIO::SearchResultEventHandler for an example of
26 This interface describes the basic methods required for
27 EventHandlers. These are essentially SAX methods.
29 =head1 Developer Notes
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.
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.
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.
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.
61 bioperl-l@bioperl.org - General discussion
62 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
66 Please direct usage questions or support issues to the mailing list:
68 I<bioperl-l@bioperl.org>
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.
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
81 https://redmine.open-bio.org/projects/bioperl/
83 =head1 AUTHOR - Jason Stajich
85 Email jason@bioperl.org
89 The rest of the documentation details each of the object methods.
90 Internal methods are usually preceded with a _
95 # Let the code begin...
98 package Bio
::Event
::EventHandlerI
;
102 use base
qw(Bio::Root::RootI);
107 Usage : if( $handler->will_handle($event_type) ) { ... }
108 Function: Tests if this event builder knows how to process a specific event
110 Args : event type name
116 my ($self,$type) = @_;
117 $self->throw_not_implemented();
124 =head2 start_document
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.
132 Usually, a handler will reset any internal state structures
133 when this method is called.
142 my ($self,@args) = @_;
143 $self->throw_not_implemented;
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.
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.
161 Returns : The object representing the result of parsing the input
162 stream between the calls to start_document() and this method.
169 my ($self,@args) = @_;
170 $self->throw_not_implemented;
175 Title : start_element
176 Usage : $parser->start_element
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()
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.
199 my ($self,@args) = @_;
200 $self->throw_not_implemented;
206 Usage : $parser->end_element
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
216 Args : hashref with at least 2 keys, 'Data' and 'Name'. The semantics
217 are the same as for start_element().
223 my ($self,@args) = @_;
224 $self->throw_not_implemented;
231 Usage : if( $handler->in_element($element) ) {}
233 Function: Test if we are in a particular element.
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().
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().
248 Args : A string, the name of the element (normally an attribute name or nested sub-element name).
253 my ($self,@args) = @_;
254 $self->throw_not_implemented;
258 =head2 within_element
260 Title : within_element
261 Usage : if( $handler->within_element($element) ) {}
263 Function: Test if we are within a particular kind of element.
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
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().
276 Args : string element name
282 my ($self,@args) = @_;
283 $self->throw_not_implemented;
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.
296 The context of the character data being passed can be
297 determined by calling the in_element() and within_element()
301 Args : string, the character data
307 my ($self,@args) = @_;
308 $self->throw_not_implemented;