XML::ESISParser(3pm)					User Contributed Perl Documentation				      XML::ESISParser(3pm)

NAME

       XML::ESISParser - Perl SAX parser using nsgmls

SYNOPSIS

	use XML::ESISParser;

	$parser = XML::ESISParser->new( [OPTIONS] );
	$result = $parser->parse( [OPTIONS] );

	$result = $parser->parse($string);

DESCRIPTION

       "XML::ESISParser" is a Perl SAX parser using the `nsgmls' command of James Clark's SGML Parser (SP), a validating XML and SGML parser.
       This man page summarizes the specific options, handlers, and properties supported by "XML::ESISParser"; please refer to the Perl SAX
       standard in `"SAX.pod"' for general usage information.

       "XML::ESISParser" defaults to parsing XML and has an option for parsing SGML.

       `"nsgmls"' source, and binaries for some platforms, is available from <http://www.jclark.com/>.	`"nsgmls"' is included in both the SP and
       Jade packages.

METHODS

       new Creates a new parser object.  Default options for parsing, described below, are passed as key-value pairs or as a single hash.  Options
	   may be changed directly in the parser object unless stated otherwise.  Options passed to `"parse()"' override the default options in
	   the parser object for the duration of the parse.

OPTIONS

       The following options are supported by "XML::ESISParser":

	Handler 	 default handler to receive events
	DocumentHandler  handler to receive document events
	DTDHandler	 handler to receive DTD events
	ErrorHandler	 handler to receive error events
	Source		 hash containing the input source for parsing
	IsSGML		 the document to be parsed is in SGML

       If no handlers are provided then all events will be silently ignored.

       If a single string argument is passed to the `"parse()"' method, it is treated as if a `"Source"' option was given with a `"String"'
       parameter.

       The `"Source"' hash may contain the following parameters:

	ByteStream	 The raw byte stream (file handle) containing the
			 document.
	String		 A string containing the document.
	SystemId	 The system identifier (URI) of the document.

       If more than one of `"ByteStream"', `"String"', or `"SystemId"', then preference is given first to `"ByteStream"', then `"String"', then
       `"SystemId"'.

HANDLERS

       The following handlers and properties are supported by "XML::ESISParser":

   DocumentHandler methods
       start_document
	   Receive notification of the beginning of a document.

	   No properties defined.

       end_document
	   Receive notification of the end of a document.

	   No properties defined.

       start_element
	   Receive notification of the beginning of an element.

	    Name	     The element type name.
	    Attributes	     A hash containing the attributes attached to the
			     element, if any.
	    IncludedSubelement This element is an included subelement.
	    Empty	     This element is declared empty.

	   The `"Attributes"' hash contains only string values.  The `"Empty"' flag is not set for an element that merely has no content, it is
	   set only if the DTD declares it empty.

	   BETA: Attribute values currently do not expand SData entities into entity objects, they are still in the system data notation used by
	   nsgmls (inside `|').  A future version of XML::ESISParser will also convert other types of attributes into their respective objects,
	   currently just their notation or entity names are given.

       end_element
	   Receive notification of the end of an element.

	    Name	     The element type name.

       characters
	   Receive notification of character data.

	    Data	     The characters from the document.

       record_end
	   Receive notification of a record end sequence.  XML applications should convert this to a new-line.

       processing_instruction
	   Receive notification of a processing instruction.

	    Target	     The processing instruction target in XML.
	    Data	     The processing instruction data, if any.

       internal_entity_ref
	   Receive notification of a system data (SData) internal entity reference.

	    Name	     The name of the internal entity reference.

       external_entity_ref
	   Receive notification of a external entity reference.

	    Name	     The name of the external entity reference.

       start_subdoc
	   Receive notification of the start of a sub document.

	    Name	     The name of the external entity reference.

       end_subdoc
	   Receive notification of the end of a sub document.

	    Name	     The name of the external entity reference.

       conforming
	   Receive notification that the document just parsed conforms to it's document type declaration (DTD).

	   No properties defined.

   DTDHandler methods
       external_entity_decl
	   Receive notification of an external entity declaration.

	    Name	     The entity's entity name.
	    Type	     The entity's type (CDATA, NDATA, etc.)
	    SystemId	     The entity's system identifier.
	    PublicId	     The entity's public identifier, if any.
	    GeneratedId      Generated system identifiers, if any.

       internal_entity_decl
	   Receive notification of an internal entity declaration.

	    Name	     The entity's entity name.
	    Type	     The entity's type (CDATA, NDATA, etc.)
	    Value	     The entity's character value.

       notation_decl
	   Receive notification of a notation declaration.

	    Name	     The notation's name.
	    SystemId	     The notation's system identifier.
	    PublicId	     The notation's public identifier, if any.
	    GeneratedId      Generated system identifiers, if any.

       subdoc_entity_decl
	   Receive notification of a subdocument entity declaration.

	    Name	     The entity's entity name.
	    SystemId	     The entity's system identifier.
	    PublicId	     The entity's public identifier, if any.
	    GeneratedId      Generated system identifiers, if any.

       external_sgml_entity_decl
	   Receive notification of an external SGML-entity declaration.

	    Name	     The entity's entity name.
	    SystemId	     The entity's system identifier.
	    PublicId	     The entity's public identifier, if any.
	    GeneratedId      Generated system identifiers, if any.

AUTHOR

       Ken MacLeod, ken@bitsko.slc.ut.us

SEE ALSO

       perl(1), PerlSAX.pod(3)

	Extensible Markup Language (XML) <http://www.w3c.org/XML/>
	SAX 1.0: The Simple API for XML <http://www.megginson.com/SAX/>
	SGML Parser (SP) <http://www.jclark.com/sp/>

perl v5.10.1							    2003-10-21						      XML::ESISParser(3pm)