Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bio::Event::EventHandlUser3Contributed Perl DocumeBio::Event::EventHandlerI(3)

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

   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

perl v5.24.1			  2017-07-08	  Bio::Event::EventHandlerI(3)

NAME | SYNOPSIS | DESCRIPTION | Developer Notes | FEEDBACK | AUTHOR - Jason Stajich | APPENDIX

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bio::Event::EventHandlerI&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help