This manual page was copied from the XML::Parser distribution (version 2.27) written by Clark Cooper. You can find newer versions at CPAN.
XML::Parser - A perl module for parsing XML documents
use XML::Parser;
$p1 = new XML::Parser(Style => 'Debug');
$p1->parsefile('REC-xml-19980210.xml');
$p1->parse('<foo id="me">Hello World</foo>');
# Alternative
$p2 = new XML::Parser(Handlers => {Start => \&handle_start,
End => \&handle_end,
Char => \&handle_char});
$p2->parse($socket);
# Another alternative $p3 = new XML::Parser(ErrorContext => 2);
$p3->setHandlers(Char => \&text, Default => \&other);
open(FOO, 'xmlgenerator |'); $p3->parse(*FOO, ProtocolEncoding => 'ISO-8859-1'); close(FOO);
$p3->parsefile('junk.xml', ErrorContext => 3);
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 /Style and/or
/Handlers options, or by /setHandlers method. These all provide
mechanisms for XML::Parser to set the handlers needed by XML::Parser::Expat.
If neither 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.
new
* Style
* Handlers
* Pkg
* ErrorContext
* ProtocolEncoding
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 @Encoding_Path list. Check "ENCODINGS" for
more information on encoding maps. Setting the protocol encoding overrides
any encoding in the XML declaration.
* Namespaces
* NoExpand
* Stream_Delimiter
* ParseParamEnt
* Non-Expat-Options
setHandlers(TYPE, HANDLER [, TYPE, HANDLER [...]])
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 [...]])
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.
parsestring
parsefile(FILE [, OPT => OPT_VALUE [...]])
parse_start([ OPT => OPT_VALUE [...]])
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.
Expat is an event based parser. As the parser recognizes parts of the document (say the start or end tag for an XML element), then any handlers registered 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 XML::Parser::Expat/"METHODS" for a discussion of the methods that can be called on this object.
This is called just before the parsing of the document starts.
This is called just after parsing has finished, but only if no errors occurred during the parse. Parse returns what this returns.
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.
This event is generated when an XML end tag is recognized. Note that an XML empty tag (<foo/>) generates both a start and an end event.
This event is generated when non-markup is recognized. The non-markup sequence of characters is in String. A single non-markup sequence of characters 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.
This event is generated when a processing instruction is recognized.
This event is generated when a comment is recognized.
This is called at the start of a CDATA section.
This is called at the end of a CDATA section.
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.
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.
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.
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 indicates the external entity couldn't be found and will generate a parse error.
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). The parser will close the filehandle after using it.
A default handler, XML::Parser::default_ext_ent_handler, is installed for this. It only handles the file URL method and it assumes "file:" if it isn't there. 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.
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 parameter entity declaration, then a '%' will be prefixed to the name.
Note that this handler and the Unparsed handler above overlap. If both are set, then this handler will not be called for unparsed entities.
The element handler is called when an element declaration is found. Name is the element name, and Model is the content model as a string.
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 character). If Fixed is true, then this is a fixed attribute.
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, otherwise it's undefined. Pubid is the public id of the document type, which will be undefined if no public id was given. Internal is the internal subset, given as a string. If there was no internal subset, it will be undefined. 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.
This handler is called for xml declarations. Version is a string containg the version. Encoding is either undefined or contains an encoding string. Standalone will be either true, false, or undefined if the standalone attribute is yes, no, or not made respectively.
This just prints out the document in outline form. Nothing special is returned by parse.
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.
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:
<foo><head id="a">Hello <em>there</em></head><bar>Howdy<ref/></bar>do</foo>
would be: Tag Content ================================================================== [foo, [{}, head, [{id => "a"}, 0, "Hello ", em, [{}, 0, "there"]], bar, [ {}, 0, "Howdy", ref, [{}]], 0, "do" ] ]
The root document "foo", has 3 children: a "head" element, a "bar" element and the text "do". After the empty attribute hash, these are represented in it's contents by 3 tag-content pairs.
This is similar to the Tree style, except that a hash object is created for each element. The corresponding object will be in the class whose name is created by appending "::" and the element name to the package set with the Pkg option. Non-markup text will be in the ::Characters class. The contents of the corresponding object will be in an anonymous array that is the value of the Kids property for that object.
This style also uses the Pkg package. If none of the subs that this style looks for is there, then the effect of parsing with this style is to print a canonical copy of the document without comments or declarations. All the subs receive as their 1st parameter the Expat instance for the document they're parsing.
It looks for the following routines:
* StartDocument
* StartTag
* EndTag
* Text
* PI
* EndDocument
XML documents may be encoded in character sets other than Unicode as long as they may be mapped into the Unicode character set. Expat has further restrictions on encodings. Read the xmlparse.h header file in the expat distribution to see details on these restrictions.
Expat has built-in encodings for: UTF-8, ISO-8859-1, UTF-16, and
US-ASCII. Encodings are set either through the XML declaration
encoding attribute or through the ProtocolEncoding option to XML::Parser
or XML::Parser::Expat.
For encodings other than the built-ins, expat calls the function load_encoding in the Expat package with the encoding name. This function looks for a file in the path list @XML::Parser::Expat::Encoding_Path, that matches the lower-cased name with a '.enc' extension. The first one it finds, it loads.
If you wish to build your own encoding maps, check out the XML::Encoding module from CPAN.
Larry Wall <larry@wall.org> wrote version 1.0.
Clark Cooper <coopercc@netheaven.com> picked up support, changed the API for this version (2.x), provided documentation, and added some standard package features.