.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 "XML::Parser::PerlSAX 3"
.TH XML::Parser::PerlSAX 3 "2003-10-21" "perl v5.26.3" "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"
XML::Parser::PerlSAX \- Perl SAX parser using XML::Parser
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use XML::Parser::PerlSAX;
\&
\& $parser = XML::Parser::PerlSAX\->new( [OPTIONS] );
\& $result = $parser\->parse( [OPTIONS] );
\&
\& $result = $parser\->parse($string);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`XML::Parser::PerlSAX\*(C'\fR is a PerlSAX parser using the XML::Parser
module.  This man page summarizes the specific options, handlers, and
properties supported by \f(CW\*(C`XML::Parser::PerlSAX\*(C'\fR; please refer to the
PerlSAX standard in `\f(CW\*(C`PerlSAX.pod\*(C'\fR' for general usage information.
.SH "METHODS"
.IX Header "METHODS"
.IP "new" 4
.IX Item "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 `\f(CW\*(C`parse()\*(C'\fR' override the default options in the
parser object for the duration of the parse.
.IP "parse" 4
.IX Item "parse"
Parses a document.  Options, described below, are passed as key-value
pairs or as a single hash.  Options passed to `\f(CW\*(C`parse()\*(C'\fR' override
default options in the parser object.
.IP "location" 4
.IX Item "location"
Returns the location as a hash:
.Sp
.Vb 9
\&  ColumnNumber    The column number of the parse.
\&  LineNumber      The line number of the parse.
\&  BytePosition    The current byte position of the parse.
\&  PublicId        A string containing the public identifier, or undef
\&                  if none is available.
\&  SystemId        A string containing the system identifier, or undef
\&                  if none is available.
\&  Base            The current value of the base for resolving relative
\&                  URIs.
.Ve
.Sp
\&\s-1ALPHA WARNING:\s0 The `\f(CW\*(C`SystemId\*(C'\fR' and `\f(CW\*(C`PublicId\*(C'\fR' properties returned
are the system and public identifiers of the document passed to
`\f(CW\*(C`parse()\*(C'\fR', not the identifiers of the currently parsing external
entity.  The column, line, and byte positions \fIare\fR of the current
entity being parsed.
.SH "OPTIONS"
.IX Header "OPTIONS"
The following options are supported by \f(CW\*(C`XML::Parser::PerlSAX\*(C'\fR:
.PP
.Vb 9
\& Handler          default handler to receive events
\& DocumentHandler  handler to receive document events
\& DTDHandler       handler to receive DTD events
\& ErrorHandler     handler to receive error events
\& EntityResolver   handler to resolve entities
\& Locale           locale to provide localisation for errors
\& Source           hash containing the input source for parsing
\& UseAttributeOrder set to true to provide AttributeOrder and Defaulted
\&                   properties in \`start_element()\*(Aq
.Ve
.PP
If no handlers are provided then all events will be silently ignored,
except for `\f(CW\*(C`fatal_error()\*(C'\fR' which will cause a `\f(CW\*(C`die()\*(C'\fR' to be
called after calling `\f(CW\*(C`end_document()\*(C'\fR'.
.PP
If a single string argument is passed to the `\f(CW\*(C`parse()\*(C'\fR' method, it
is treated as if a `\f(CW\*(C`Source\*(C'\fR' option was given with a `\f(CW\*(C`String\*(C'\fR'
parameter.
.PP
The `\f(CW\*(C`Source\*(C'\fR' hash may contain the following parameters:
.PP
.Vb 6
\& ByteStream       The raw byte stream (file handle) containing the
\&                  document.
\& String           A string containing the document.
\& SystemId         The system identifier (URI) of the document.
\& PublicId         The public identifier.
\& Encoding         A string describing the character encoding.
.Ve
.PP
If more than one of `\f(CW\*(C`ByteStream\*(C'\fR', `\f(CW\*(C`String\*(C'\fR', or `\f(CW\*(C`SystemId\*(C'\fR',
then preference is given first to `\f(CW\*(C`ByteStream\*(C'\fR', then `\f(CW\*(C`String\*(C'\fR',
then `\f(CW\*(C`SystemId\*(C'\fR'.
.SH "HANDLERS"
.IX Header "HANDLERS"
The following handlers and properties are supported by
\&\f(CW\*(C`XML::Parser::PerlSAX\*(C'\fR:
.SS "DocumentHandler methods"
.IX Subsection "DocumentHandler methods"
.IP "start_document" 4
.IX Item "start_document"
Receive notification of the beginning of a document.
.Sp
No properties defined.
.IP "end_document" 4
.IX Item "end_document"
Receive notification of the end of a document.
.Sp
No properties defined.
.IP "start_element" 4
.IX Item "start_element"
Receive notification of the beginning of an element.
.Sp
.Vb 3
\& Name             The element type name.
\& Attributes       A hash containing the attributes attached to the
\&                  element, if any.
.Ve
.Sp
The `\f(CW\*(C`Attributes\*(C'\fR' hash contains only string values.
.Sp
If the `\f(CW\*(C`UseAttributeOrder\*(C'\fR' parser option is true, the following
properties are also passed to `\f(CW\*(C`start_element\*(C'\fR':
.Sp
.Vb 7
\& AttributeOrder   An array of attribute names in the order they were
\&                  specified, followed by the defaulted attribute
\&                  names.
\& Defaulted        The index number of the first defaulted attribute in
\&                  \`AttributeOrder.  If this index is equal to the
\&                  length of \`AttributeOrder\*(Aq, there were no defaulted
\&                  values.
.Ve
.Sp
Note to \f(CW\*(C`XML::Parser\*(C'\fR users:  `\f(CW\*(C`Defaulted\*(C'\fR' will be half the value of
\&\f(CW\*(C`XML::Parser::Expat\*(C'\fR's `\f(CW\*(C`specified_attr()\*(C'\fR' function because only
attribute names are provided, not their values.
.IP "end_element" 4
.IX Item "end_element"
Receive notification of the end of an element.
.Sp
.Vb 1
\& Name             The element type name.
.Ve
.IP "characters" 4
.IX Item "characters"
Receive notification of character data.
.Sp
.Vb 1
\& Data             The characters from the XML document.
.Ve
.IP "processing_instruction" 4
.IX Item "processing_instruction"
Receive notification of a processing instruction.
.Sp
.Vb 2
\& Target           The processing instruction target. 
\& Data             The processing instruction data, if any.
.Ve
.IP "comment" 4
.IX Item "comment"
Receive notification of a comment.
.Sp
.Vb 1
\& Data             The comment data, if any.
.Ve
.IP "start_cdata" 4
.IX Item "start_cdata"
Receive notification of the start of a \s-1CDATA\s0 section.
.Sp
No properties defined.
.IP "end_cdata" 4
.IX Item "end_cdata"
Receive notification of the end of a \s-1CDATA\s0 section.
.Sp
No properties defined.
.IP "entity_reference" 4
.IX Item "entity_reference"
Receive notification of an internal entity reference.  If this handler
is defined, internal entities will not be expanded and not passed to
the `\f(CW\*(C`characters()\*(C'\fR' handler.  If this handler is not defined,
internal entities will be expanded if possible and passed to the
`\f(CW\*(C`characters()\*(C'\fR' handler.
.Sp
.Vb 2
\& Name             The entity reference name
\& Value            The entity reference value
.Ve
.SS "DTDHandler methods"
.IX Subsection "DTDHandler methods"
.IP "notation_decl" 4
.IX Item "notation_decl"
Receive notification of a notation declaration event.
.Sp
.Vb 4
\& Name             The notation name.
\& PublicId         The notation\*(Aqs public identifier, if any.
\& SystemId         The notation\*(Aqs system identifier, if any.
\& Base             The base for resolving a relative URI, if any.
.Ve
.IP "unparsed_entity_decl" 4
.IX Item "unparsed_entity_decl"
Receive notification of an unparsed entity declaration event.
.Sp
.Vb 4
\& Name             The unparsed entity\*(Aqs name.
\& SystemId         The entity\*(Aqs system identifier.
\& PublicId         The entity\*(Aqs public identifier, if any.
\& Base             The base for resolving a relative URI, if any.
.Ve
.IP "entity_decl" 4
.IX Item "entity_decl"
Receive notification of an entity declaration event.
.Sp
.Vb 5
\& Name             The entity name.
\& Value            The entity value, if any.
\& PublicId         The notation\*(Aqs public identifier, if any.
\& SystemId         The notation\*(Aqs system identifier, if any.
\& Notation         The notation declared for this entity, if any.
.Ve
.Sp
For internal entities, the `\f(CW\*(C`Value\*(C'\fR' parameter will contain the value
and the `\f(CW\*(C`PublicId\*(C'\fR', `\f(CW\*(C`SystemId\*(C'\fR', and `\f(CW\*(C`Notation\*(C'\fR' will be
undefined.  For external entities, the `\f(CW\*(C`Value\*(C'\fR' parameter will be
undefined, the `\f(CW\*(C`SystemId\*(C'\fR' parameter will have the system id, the
`\f(CW\*(C`PublicId\*(C'\fR' parameter will have the public id if it was provided (it
will be undefined otherwise), the `\f(CW\*(C`Notation\*(C'\fR' parameter will contain
the notation name for unparsed entities.  If this is a parameter entity
declaration, then a '%' will be prefixed to the entity name.
.Sp
Note that `\f(CW\*(C`entity_decl()\*(C'\fR' and `\f(CW\*(C`unparsed_entity_decl()\*(C'\fR' overlap.
If both methods are implemented by a handler, then this handler will
not be called for unparsed entities.
.IP "element_decl" 4
.IX Item "element_decl"
Receive notification of an element declaration event.
.Sp
.Vb 2
\& Name             The element type name.
\& Model            The content model as a string.
.Ve
.IP "attlist_decl" 4
.IX Item "attlist_decl"
Receive notification of an attribute list declaration event.
.Sp
This handler is called for each attribute in an \s-1ATTLIST\s0 declaration
found in the internal subset. So an \s-1ATTLIST\s0 declaration that has
multiple attributes will generate multiple calls to this handler.
.Sp
.Vb 4
\& ElementName      The element type name.
\& AttributeName    The attribute name.
\& Type             The attribute type.
\& Fixed            True if this is a fixed attribute.
.Ve
.Sp
The default for `\f(CW\*(C`Type\*(C'\fR' is the default value, which will either be
\&\*(L"#REQUIRED\*(R", \*(L"#IMPLIED\*(R" or a quoted string (i.e. the returned string
will begin and end with a quote character).
.IP "doctype_decl" 4
.IX Item "doctype_decl"
Receive notification of a \s-1DOCTYPE\s0 declaration event.
.Sp
.Vb 4
\& Name             The document type name.
\& SystemId         The document\*(Aqs system identifier.
\& PublicId         The document\*(Aqs public identifier, if any.
\& Internal         The internal subset as a string, if any.
.Ve
.Sp
Internal will contain all whitespace, comments, processing
instructions, and declarations seen in the internal subset. The
declarations will be there whether or not they have been processed by
another handler (except for unparsed entities processed by the
Unparsed handler).  However, comments and processing instructions will
not appear if they've been processed by their respective handlers.
.IP "xml_decl" 4
.IX Item "xml_decl"
Receive notification of an \s-1XML\s0 declaration event.
.Sp
.Vb 3
\& Version          The version.
\& Encoding         The encoding string, if any.
\& Standalone       True, false, or undefined if not declared.
.Ve
.SS "EntityResolver"
.IX Subsection "EntityResolver"
.IP "resolve_entity" 4
.IX Item "resolve_entity"
Allow the handler to resolve external entities.
.Sp
.Vb 4
\& Name             The notation name.
\& SystemId         The notation\*(Aqs system identifier.
\& PublicId         The notation\*(Aqs public identifier, if any.
\& Base             The base for resolving a relative URI, if any.
.Ve
.Sp
`\f(CW\*(C`resolve_entity()\*(C'\fR' should return undef to request that the parser
open a regular \s-1URI\s0 connection to the system identifier or a hash
describing the new input source.  This hash has the same properties as
the `\f(CW\*(C`Source\*(C'\fR' parameter to `\f(CW\*(C`parse()\*(C'\fR':
.Sp
.Vb 9
\&  PublicId    The public identifier of the external entity being
\&              referenced, or undef if none was supplied. 
\&  SystemId    The system identifier of the external entity being
\&              referenced.
\&  String      String containing XML text
\&  ByteStream  An open file handle.
\&  CharacterStream
\&              An open file handle.
\&  Encoding    The character encoding, if known.
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Ken MacLeod, ken@bitsko.slc.ut.us
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBPerlSAX.pod\fR\|(3)
.PP
.Vb 2
\& Extensible Markup Language (XML) <http://www.w3c.org/XML/>
\& SAX 1.0: The Simple API for XML <http://www.megginson.com/SAX/>
.Ve
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 528:" 4
.IX Item "Around line 528:"
You forgot a '=back' before '=head1'