NAME
Bio::Event::EventHandlerI - An Event Handler Interface
SYNOPSIS
# do not use this module directly
# See Bio::SearchIO::SearchResultEventHandler for an example of
# implementation.DESCRIPTION
This interface describes the basic methods required for EventHandlers. These are essentially SAX methods.
Developer Notes
EventHandlerI implementations are used in the BioPerl IO systems to decouple the task of tokenizing the input stream into data elements and their attributes, which is format-specific, and the task of collecting those elements and attributes into whatever is the result of a parser, which is specific to the kind of result to be produced, such as BioPerl objects, a tabular or array data structure, etc.
You can think of EventHandlerI-compliant parsers as faking a SAX XML parser, making their input (typically a non-XML document) behave as if it were XML. The overhead to do this can be quite substantial, at the gain of not having to duplicate the parsing code in order to change the parsing result, and not having to duplicate the logic of instantiating objects between parsers for different formats that all give rise to the same types of objects. This is perhaps best illustrated by the Bio::SearchIO system, where many different formats exist for sequence similarity and pairwise sequence alignment exist that essentially all result in Bio::Search objects.
The method names and their invocation semantics follow their XML SAX equivalents, see http://www.saxproject.org/apidoc/, especially the org.xml.sax.ContentHandler interface.
FEEDBACK
Mailing Lists
User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to the Bioperl mailing list. Your participation is much appreciated.
bioperl-l@bioperl.org - General discussion
http://bioperl.org/wiki/Mailing_lists - About the mailing listsSupport
Please direct usage questions or support issues to the mailing list:
bioperl-l@bioperl.org
rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible.
Reporting Bugs
Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their resolution. Bug reports can be submitted via the web:
https://github.com/bioperl/bioperl-live/issuesAUTHOR - Jason Stajich
Email jason@bioperl.org
APPENDIX
The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
will_handle
Title : will_handle
Usage : if( $handler->will_handle($event_type) ) { ... }
Function: Tests if this event builder knows how to process a specific event
Returns : boolean
Args : event type nameSAX methods
start_document
Title : start_document
Usage : $resultObj = $parser->start_document();
Function: Receive notification of the beginning of a document (the
input file of a parser). The parser will invoke this method
only once, before any other event callbacks.
Usually, a handler will reset any internal state structures
when this method is called.
Returns : none
Args : noneend_document
Title : end_document
Usage : $parser->end_document();
Function: Receive notification of the end of a document (normally the
input file of a parser). The parser will invoke this method
only once, and it will be the last method invoked during
the parse of the document. The parser shall not invoke this
method until it has either abandoned parsing (because of an
unrecoverable error) or reached the end of input.
Unlike the XML SAX signature of this method, this method is
expected to return the object representing the result of
parsing the document.
Returns : The object representing the result of parsing the input
stream between the calls to start_document() and this method.
Args : nonestart_element
Title : start_element
Usage : $parser->start_element
Function: Receive notification of the beginning of an element. The
Parser will invoke this method at the beginning of every
element in the input stream; there will be a corresponding
end_element() event for every start_element() event (even when
the element is empty). All of the element's content will be
reported, in order, before the corresponding end_element()
event.
Returns : none
Args : A hashref with at least 2 keys: 'Data' and 'Name'. The value
for 'Name' is expected to be the type of element being
encountered; the understood values will depend on the IO
parser to which this interface is being applied. Likewise, the
value for 'Data' will be specific to event handler
implementions, and the specific data chunking needs of input
formats to be handled efficiently.end_element
Title : end_element
Usage : $parser->end_element
Function: Receive notification of the end of an element. The parser
will invoke this method at the end of every element in the
input stream; there will be a corresponding start_element()
event for every end_element() event (even when the element
is empty).
Returns : none
Args : hashref with at least 2 keys, 'Data' and 'Name'. The semantics
are the same as for start_element().in_element
Title : in_element
Usage : if( $handler->in_element($element) ) {}
Function: Test if we are in a particular element.
Normally, in_element() will test for particular attributes,
or nested elements, within a containing
element. Conversely, the containing element can be queries
with within_element(). The names understood as argument
should be the same as the ones understood for the 'Name'
key in start_element() and end_element().
Typically, handler implementations will call this method
from within the characters() method to determine the
context of the data that were passed to characters().
Returns : boolean
Args : A string, the name of the element (normally an attribute name or nested sub-element name). within_element
Title : within_element
Usage : if( $handler->within_element($element) ) {}
Function: Test if we are within a particular kind of element.
Normally, the element type names understood as argument
values will be for containing elements or data
chunks. Conversely, in_element() can be used to test
whether an attribute or nested element is the ccurrent
context.
Typically, a handler will call this method from within the
characters() method to determine the context for the data
that were passed to characters().
Returns : boolean
Args : string element name characters
Title : characters
Usage : $parser->characters($str)
Function: Receive notification of character data. The parser will
call this method to report values of attributes, or larger
data chunks, depending on the IO subsystem and event
handler implementation. Values may be whitespace-padded
even if the whitespace is insignificant for the format.
The context of the character data being passed can be
determined by calling the in_element() and within_element()
methods.
Returns : none
Args : string, the character data