Parser(3) User Contributed Perl Documentation Parser(3)
NAME
XML::Parser - A perl module for parsing XML documents
SYNOPSIS
use XML::Parser;
$p1 = XML::Parser->new(Style => 'Debug');
$p1->parsefile('REC-xml-19980210.xml');
$p1->parse('Hello World');
# Alternative
$p2 = XML::Parser->new(Handlers => {Start => \&handle_start,
End => \&handle_end,
Char => \&handle_char});
$p2->parse($socket);
# Another alternative
$p3 = XML::Parser->new(ErrorContext => 2);
$p3->setHandlers(Char => \&text,
Default => \&other);
open(my $fh, 'xmlgenerator |');
$p3->parse($fh, ProtocolEncoding => 'ISO-8859-1');
close($fh);
$p3->parsefile('junk.xml', ErrorContext => 3);
DESCRIPTION
This module provides ways to parse XML documents. It is built on top of
XML::Parser::Expat, which is a lower level interface to James Clark's expat
library. Each call to one of the parsing methods creates a new instance of
XML::Parser::Expat which is then used to parse the document. Expat options
may be provided when the XML::Parser object is created. These options are
then passed on to the Expat object on each parse call. They can also be
given as extra arguments to the parse methods, in which case they override
options given at XML::Parser creation time.
The behavior of the parser is controlled either by "STYLES" and/or "HAN-
DLERS" options, or by "setHandlers" method. These all provide mechanisms
for XML::Parser to set the handlers needed by XML::Parser::Expat. If nei-
ther "Style" nor "Handlers" are specified, then parsing just checks the
document for being well-formed.
When underlying handlers get called, they receive as their first parameter
the Expat object, not the Parser object.
METHODS
new This is a class method, the constructor for XML::Parser. Options are
passed as keyword value pairs. Recognized options are:
* Style
This option provides an easy way to create a given style of parser.
The built in styles are: "Debug", "Subs", "Tree", "Objects", and
"Stream". These are all defined in separate packages under
"XML::Parser::Style::*", and you can find further documentation for
each style both below, and in those packages.
Custom styles can be provided by giving a full package name con-
taining at least one '::'. This package should then have subs de-
fined for each handler it wishes to have installed. See "STYLES"
below for a discussion of each built in style.
* Handlers
When provided, this option should be an anonymous hash containing
as keys the type of handler and as values a sub reference to handle
that type of event. All the handlers get passed as their 1st para-
meter the instance of expat that is parsing the document. Further
details on handlers can be found in "HANDLERS". Any handler set
here overrides the corresponding handler set with the Style option.
* Pkg
Some styles will refer to subs defined in this package. If not pro-
vided, it defaults to the package which called the constructor.
* ErrorContext
This is an Expat option. When this option is defined, errors are
reported in context. The value should be the number of lines to
show on either side of the line in which the error occurred.
* ProtocolEncoding
This is an Expat option. This sets the protocol encoding name. It
defaults to none. The built-in encodings are: "UTF-8",
"ISO-8859-1", "UTF-16", and "US-ASCII". Other encodings may be used
if they have encoding maps in one of the directories in the @Encod-
ing_Path list. Check "ENCODINGS" for more information on encoding
maps. Setting the protocol encoding overrides any encoding in the
XML declaration.
* Namespaces
This is an Expat option. If this is set to a true value, then name-
space processing is done during the parse. See "Namespaces" in
XML::Parser::Expat for further discussion of namespace processing.
* NoExpand
This is an Expat option. Normally, the parser will try to expand
references to entities defined in the internal subset. If this op-
tion is set to a true value, and a default handler is also set,
then the default handler will be called when an entity reference is
seen in text. This has no effect if a default handler has not been
registered, and it has no effect on the expansion of entity refer-
ences inside attribute values.
* Stream_Delimiter
This is an Expat option. It takes a string value. When this string
is found alone on a line while parsing from a stream, then the
parse is ended as if it saw an end of file. The intended use is
with a stream of xml documents in a MIME multipart format. The
string should not contain a trailing newline.
* ParseParamEnt
This is an Expat option. Unless standalone is set to "yes" in the
XML declaration, setting this to a true value allows the external
DTD to be read, and parameter entities to be parsed and expanded.
Implicit vs explicit parameter entity parsing: When "ParseParamEnt"
is not set, parameter entity references (e.g. "%foo;") in the in-
ternal DTD subset are passed through to the Default handler as lit-
eral text. This is the mode that XML::Twig and other DTD
round-tripping tools rely on.
When "ParseParamEnt" is set to a true value, or when a declaration
handler (Entity, Element, or Attlist) is registered, parameter en-
tity parsing is activated. In this mode, PE references are resolved
by expat (via the ExternEnt handler) and subsequent declarations
are routed to their dedicated declaration handlers instead of the
Default handler.
* NoLWP
This option has no effect if the ExternEnt or ExternEntFin handlers
are directly set. Otherwise, if true, it forces the use of a file
based external entity handler.
* BillionLaughsAttackProtectionMaximumAmplification
Sets the maximum amplification factor for the Billion Laughs attack
protection. See "SECURITY" below for details.
This is an Expat option. Requires libexpat >= 2.4.0 built with
"XML_DTD" or "XML_GE".
* BillionLaughsAttackProtectionActivationThreshold
Sets the activation threshold (in bytes) for the Billion Laughs at-
tack protection. See "SECURITY" below for details.
This is an Expat option. Requires libexpat >= 2.4.0 built with
"XML_DTD" or "XML_GE".
* AllocTrackerMaximumAmplification
Sets the maximum amplification factor for the allocation tracker.
See "SECURITY" below for details.
This is an Expat option. Requires libexpat >= 2.7.2 built with
"XML_DTD" or "XML_GE".
* AllocTrackerActivationThreshold
Sets the activation threshold (in bytes) for the allocation
tracker. See "SECURITY" below for details.
This is an Expat option. Requires libexpat >= 2.7.2 built with
"XML_DTD" or "XML_GE".
* ReparseDeferralEnabled
Enables or disables reparse deferral, a security mechanism that
prevents certain token-boundary attacks. See "SECURITY" below for
details.
This is an Expat option. Requires libexpat >= 2.6.0.
* Non_Expat_Options
If provided, this should be an anonymous hash whose keys are op-
tions that shouldn't be passed to Expat. This should only be of
concern to those subclassing XML::Parser.
setHandlers(TYPE, HANDLER [, TYPE, HANDLER [...]])
This method registers handlers for various parser events. It overrides
any previous handlers registered through the Style or Handler options
or through earlier calls to setHandlers. By providing a false or unde-
fined value as the handler, the existing handler can be unset.
This method returns a list of type, handler pairs corresponding to the
input. The handlers returned are the ones that were in effect prior to
the call.
See a description of the handler types in "HANDLERS".
parse(SOURCE [, OPT => OPT_VALUE [...]])
The SOURCE parameter should either be a string containing the whole XML
document, or it should be an open IO::Handle. Constructor options to
XML::Parser::Expat given as keyword-value pairs may follow the SOURCE
parameter. These override, for this call, any options or attributes
passed through from the XML::Parser instance.
A die call is thrown if a parse error occurs. Otherwise it will return
1 or whatever is returned from the Final handler, if one is installed.
In other words, what parse may return depends on the style.
See "ERROR HANDLING" below for how to catch and handle parse errors.
parsestring
This is just an alias for parse for backwards compatibility.
parsefile(FILE [, OPT => OPT_VALUE [...]])
Open FILE for reading, then call parse with the open handle. The file
is closed no matter how parse returns. A die call is thrown if the file
cannot be opened or if a parse error occurs. Returns what parse re-
turns.
parse_start([ OPT => OPT_VALUE [...]])
Create and return a new instance of XML::Parser::ExpatNB. Constructor
options may be provided. If an init handler has been provided, it is
called before returning the ExpatNB object. Documents are parsed by
making incremental calls to the parse_more method of this object, which
takes a string. A single call to the parse_done method of this object,
which takes no arguments, indicates that the document is finished.
If there is a final handler installed, it is executed by the parse_done
method before returning and the parse_done method returns whatever is
returned by the final handler.
HANDLERS
Expat is an event based parser. As the parser recognizes parts of the docu-
ment (say the start or end tag for an XML element), then any handlers reg-
istered for that type of an event are called with suitable parameters. All
handlers receive an instance of XML::Parser::Expat as their first argument.
See "METHODS" in XML::Parser::Expat for a discussion of the methods that
can be called on this object.
Init (Expat)
This is called just before the parsing of the document starts.
Final (Expat)
This is called just after parsing has finished, but only if no errors oc-
curred during the parse. Parse returns what this returns.
Start (Expat, Element [, Attr, Val [,...]])
This event is generated when an XML start tag is recognized. Element is the
name of the XML element type that is opened with the start tag. The Attr &
Val pairs are generated for each attribute in the start tag.
End (Expat, Element)
This event is generated when an XML end tag is recognized. Note that an XML
empty tag () generates both a start and an end event.
Char (Expat, String)
This event is generated when non-markup is recognized. The non-markup se-
quence of characters is in String. A single non-markup sequence of charac-
ters may generate multiple calls to this handler. Whatever the encoding of
the string in the original document, this is given to the handler in UTF-8.
Important: Because the underlying expat library parses in fixed-size
chunks, character data that spans a buffer boundary will arrive as two or
more consecutive Char events. This typically occurs with files larger than
about 32 KiB and is not a bug. To obtain the complete text of an element,
accumulate the strings delivered between Start and End events:
my $current_text;
sub start_handler { $current_text = ''; }
sub char_handler { $current_text .= $_[1]; }
sub end_handler { print "complete text: $current_text\n"; }
The Stream style ("XML::Parser::Style::Stream") already performs this accu-
mulation automatically.
Proc (Expat, Target, Data)
This event is generated when a processing instruction is recognized.
Comment (Expat, Data)
This event is generated when a comment is recognized.
CdataStart (Expat)
This is called at the start of a CDATA section.
CdataEnd (Expat)
This is called at the end of a CDATA section.
Default (Expat, String)
This is called for any characters that don't have a registered handler.
This includes both characters that are part of markup for which no events
are generated (markup declarations) and characters that could generate
events, but for which no handler has been registered.
Whatever the encoding in the original document, the string is returned to
the handler in UTF-8.
Unparsed (Expat, Entity, Base, Sysid, Pubid, Notation)
This is called for a declaration of an unparsed entity. Entity is the name
of the entity. Base is the base to be used for resolving a relative URI.
Sysid is the system id. Pubid is the public id. Notation is the notation
name. Base and Pubid may be undefined.
Notation (Expat, Notation, Base, Sysid, Pubid)
This is called for a declaration of notation. Notation is the notation
name. Base is the base to be used for resolving a relative URI. Sysid is
the system id. Pubid is the public id. Base, Sysid, and Pubid may all be
undefined.
ExternEnt (Expat, Base, Sysid, Pubid)
This is called when an external entity is referenced. Base is the base to
be used for resolving a relative URI. Sysid is the system id. Pubid is the
public id. Base, and Pubid may be undefined.
This handler should either return a string, which represents the contents
of the external entity, or return an open filehandle that can be read to
obtain the contents of the external entity, or return undef, which indi-
cates the external entity couldn't be found and will generate a parse er-
ror.
If an open filehandle is returned, it must be returned as either a glob
(*FOO) or as a reference to a glob (e.g. an instance of IO::Handle).
A default handler is installed for this event. The default handler is
XML::Parser::lwp_ext_ent_handler unless the NoLWP option was provided with
a true value, otherwise XML::Parser::file_ext_ent_handler is the default
handler for external entities. Even without the NoLWP option, if the URI or
LWP modules are missing, the file based handler ends up being used after
giving a warning on the first external entity reference.
The LWP external entity handler will use proxies defined in the environment
(http_proxy, ftp_proxy, etc.).
Please note that the LWP external entity handler reads the entire entity
into a string and returns it, where as the file handler opens a filehandle.
Also note that the file external entity handler will likely choke on ab-
solute URIs or file names that don't fit the conventions of the local oper-
ating system.
The expat base method can be used to set a basename for relative pathnames.
If no basename is given, or if the basename is itself a relative name, then
it is relative to the current working directory.
ExternEntFin (Expat)
This is called after parsing an external entity. It's not called unless an
ExternEnt handler is also set. There is a default handler installed that
pairs with the default ExternEnt handler.
If you're going to install your own ExternEnt handler, then you should set
(or unset) this handler too.
Entity (Expat, Name, Val, Sysid, Pubid, Ndata, IsParam)
This is called when an entity is declared. For internal entities, the Val
parameter will contain the value and the remaining three parameters will be
undefined. For external entities, the Val parameter will be undefined, the
Sysid parameter will have the system id, the Pubid parameter will have the
public id if it was provided (it will be undefined otherwise), the Ndata
parameter will contain the notation for unparsed entities. If this is a pa-
rameter entity declaration, then the IsParam parameter is true.
Note that this handler and the Unparsed handler above overlap. If both are
set, then this handler will not be called for unparsed entities.
Element (Expat, Name, Model)
The element handler is called when an element declaration is found. Name is
the element name, and Model is the content model as an XML::Parser::Content
object. See "XML::Parser::ContentModel Methods" in XML::Parser::Expat for
methods available for this class.
Attlist (Expat, Elname, Attname, Type, Default, Fixed)
This handler is called for each attribute in an ATTLIST declaration. So an
ATTLIST declaration that has multiple attributes will generate multiple
calls to this handler. The Elname parameter is the name of the element with
which the attribute is being associated. The Attname parameter is the name
of the attribute. Type is the attribute type, given as a string. Default is
the default value, which will either be "#REQUIRED", "#IMPLIED" or a quoted
string (i.e. the returned string will begin and end with a quote charac-
ter). If Fixed is true, then this is a fixed attribute.
Doctype (Expat, Name, Sysid, Pubid, Internal)
This handler is called for DOCTYPE declarations. Name is the document type
name. Sysid is the system id of the document type, if it was provided, oth-
erwise it's undefined. Pubid is the public id of the document type, which
will be undefined if no public id was given. Internal will be true or
false, indicating whether or not the doctype declaration contains an inter-
nal subset.
* DoctypeFin (Expat)
This handler is called after parsing of the DOCTYPE declaration has fin-
ished, including any internal or external DTD declarations.
XMLDecl (Expat, Version, Encoding, Standalone)
This handler is called for xml declarations. Version is a string containing
the version. Encoding is either undefined or contains an encoding string.
Standalone will be either true, false, or undefined if the standalone at-
tribute is yes, no, or not made respectively.
STYLES
Debug
This just prints out the document in outline form. Nothing special is re-
turned by parse.
Subs
Each time an element starts, a sub by that name in the package specified by
the Pkg option is called with the same parameters that the Start handler
gets called with.
Each time an element ends, a sub with that name appended with an underscore
("_"), is called with the same parameters that the End handler gets called
with.
Nothing special is returned by parse.
Tree
Parse will return a parse tree for the document. Each node in the tree
takes the form of a tag, content pair. Text nodes are represented with a
pseudo-tag of "0" and the string that is their content. For elements, the
content is an array reference. The first item in the array is a (possibly
empty) hash reference containing attributes. The remainder of the array is
a sequence of tag-content pairs representing the content of the element.
So for example the result of parsing:
Hello thereHowdy