.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Event::EventHandlerI 3pm"
.TH Bio::Event::EventHandlerI 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Event::EventHandlerI \- An Event Handler Interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    # do not use this module directly
\&    # See Bio::SearchIO::SearchResultEventHandler for an example of
\&    # implementation.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This interface describes the basic methods required for
EventHandlers.  These are essentially \s-1SAX\s0 methods.
.SH "Developer Notes"
.IX Header "Developer Notes"
EventHandlerI implementations are used in the BioPerl \s-1IO\s0 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.
.PP
You can think of EventHandlerI-compliant parsers as faking a \s-1SAX XML\s0
parser, making their input (typically a non-XML document) behave as if
it were \s-1XML.\s0 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.
.PP
The method names and their invocation semantics follow their \s-1XML SAX\s0
equivalents, see http://www.saxproject.org/apidoc/, especially the
org.xml.sax.ContentHandler interface.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Jason Stajich"
.IX Header "AUTHOR - Jason Stajich"
Email jason@bioperl.org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "will_handle"
.IX Subsection "will_handle"
.Vb 5
\& 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
.Ve
.SS "\s-1SAX\s0 methods"
.IX Subsection "SAX methods"
.SS "start_document"
.IX Subsection "start_document"
.Vb 5
\& 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
.Ve
.SS "end_document"
.IX Subsection "end_document"
.Vb 8
\& 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
.Ve
.SS "start_element"
.IX Subsection "start_element"
.Vb 2
\& 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\*(Aqs content will be
\&           reported, in order, before the corresponding end_element()
\&           event.
\&
\& Returns : none
\& Args : A hashref with at least 2 keys: \*(AqData\*(Aq and \*(AqName\*(Aq. The value
\&        for \*(AqName\*(Aq 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 \*(AqData\*(Aq will be specific to event handler
\&        implementions, and the specific data chunking needs of input
\&        formats to be handled efficiently.
.Ve
.SS "end_element"
.IX Subsection "end_element"
.Vb 2
\& 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, \*(AqData\*(Aq and \*(AqName\*(Aq. The semantics
\&           are the same as for start_element().
.Ve
.SS "in_element"
.IX Subsection "in_element"
.Vb 2
\& 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 \*(AqName\*(Aq
\&           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).
.Ve
.SS "within_element"
.IX Subsection "within_element"
.Vb 2
\& 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
.Ve
.SS "characters"
.IX Subsection "characters"
.Vb 7
\& 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
.Ve