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.

  [email protected]                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

Support

Please direct usage questions or support issues to the mailing list:

[email protected]

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/issues

AUTHOR - Jason Stajich

Email [email protected]

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 name

SAX 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    : none

end_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    : none

start_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