Bio::E...andlerI(3pm)

✨ NAME ✨

Bio::Event::EventHandlerI — it's an Event Handler Interface, bestie 💖 (and yes, this is the User Contributed Perl Documentation page for it, so you're in the right place 🫶)

---

🌈 SYNOPSIS 🌈

# do not use this module directly
# See Bio::SearchIO::SearchResultEventHandler for an example of
# implementation.

ok so real talk: do NOT use this module directly 🙈 it's an interface, it's a vibe, it's a blueprint. If you want an actual example of someone implementing it, go look at Bio::SearchIO::SearchResultEventHandler. iykyk 💅

---

🦋 DESCRIPTION 🦋

This interface lays out the basic methods every EventHandler needs to have. They're basically SAX methods, no cap. ⭐

🧚 Developer Notes 🧚

So here's the tea, bestie 🍓 — EventHandlerI implementations get used all over the BioPerl IO systems, and their whole job is decoupling two things that would otherwise be glued together:

• the task of tokenizing the input stream into data elements and their attributes — which is format-specific, every format does its own thing 💫
• the task of collecting those elements and attributes into whatever is the result of a parser — which depends on what kind of result you want, like BioPerl objects, a tabular or array data structure, etc. 👑

You can literally think of EventHandlerI-compliant parsers as faking a SAX XML parser, making their input (which is typically a non-XML document) act like it was XML all along. iconic behaviour fr fr 💅

The overhead to do all that can be quite substantial ngl — but the gain is that you don't have to duplicate the parsing code just to change the parsing result, and you don't have to duplicate the logic of instantiating objects between parsers for different formats that all give rise to the same types of objects. 🙌 This is maybe best illustrated by the Bio::SearchIO system, where many different formats exist for sequence similarity and pairwise sequence alignment, and they essentially all result in Bio::Search objects. ate and left no crumbs. 🔥

The method names and their invocation semantics follow their XML SAX equivalents — go peek at 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 lists

🆘 Support 🆘

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

---

👑 AUTHOR - 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 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

⚠️ heads up bestie: unlike the XML SAX signature of this method, this one is expected to return the object representing the result of parsing the document. not the same vibe, don't get it twisted 💅

💫 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

---

and that's the whole page, bestie 🫶 this was perl v5.32.1, dated 2021-08-15, from the Bio::E...andlerI(3pm) man page — slay, go build something iconic with it 💅✨