XML::Parser::Expat#

📦 max

XML::Parser::Expat - the low-level interface of XML::Parser.

use XML::Parser;

my $p = XML::Parser->new(Handlers => {
    Start => sub { my ($expat, $elem, %attr) = @_; print "<$elem>\n" },
    Char  => sub { my ($expat, $text) = @_; print $text },
});
$p->parse('<doc><item id="1">hello</item></doc>');

Most programs use XML::Parser (or a module built on it such as XML::Twig, XML::Simple or XML::Dumper) and never call this module directly. It parses with pperl’s XML engine over libxml2, the one XML::LibXML uses too; libxml2 2.15 or newer is required, and the module fails to load with a message saying so when it is older or missing.

This is a native implementation of the CPAN distribution XML-Parser 2.59, which parses with the expat library; its XML/Parser.pm, XML/Parser/Expat.pm and the XML::Parser::Style::* modules are used unchanged. Every handler sees what it sees under expat: the same calls with the same arguments, character data split where expat splits it, and the same text, positions and lengths from recognized_string, original_string, current_byte, current_line, current_column and current_length. Errors carry expat’s messages and positions.

Differences from upstream#

expat_version reports the expat release whose interface this module provides, expat_2.6.0, since no expat is loaded.

A document with standalone="yes" has the parameter entities of its internal subset expanded, as XML 1.0 requires; expat leaves them unread, and then refuses an entity reference they declare as undefined.

Functions#

Other Functions#

ParserCreate#

ParserCreate($self, $encoding, $namespaces): a new parser for the XML::Parser::Expat object $self, as an integer handle.

ParserRelease#

ParserRelease($parser): drop the parser’s reference to its object, breaking the cycle so that the object can be freed.

ParserFree#

ParserFree($parser): free the parser and every handler it holds.

ParseString#

ParseString($parser, $string): parse a whole document.

ParseStream#

ParseStream($parser, $handle, $delim): parse from a handle, up to a line holding only $delim when it is defined.

ParsePartial#

ParsePartial($parser, $chunk): parse one more chunk of a document.

ParseDone#

ParseDone($parser): end a document parsed with ParsePartial.

UnsetAllHandlers#

UnsetAllHandlers($parser): expat’s handlers go, the element ones and the namespace ones included; what is left is the Default handler.

SetBase#

SetBase($parser, $base).

GetBase#

GetBase($parser): the base, or undef.

PositionContext#

PositionContext($parser, $lines): the input around the current position, $lines lines either side, and the position’s offset in it.

GenerateNSName#

GenerateNSName($name, $namespace, \%table, \@list): the name object for $name in $namespace, as the parser makes them.

DefaultCurrent#

DefaultCurrent($parser): pass the current event’s text to the Default handler.

RecognizedString#

RecognizedString($parser): the text of the current event.

GetErrorCode#

GetErrorCode($parser).

GetCurrentLineNumber#

GetCurrentLineNumber($parser).

GetCurrentColumnNumber#

GetCurrentColumnNumber($parser).

GetCurrentByteIndex#

GetCurrentByteIndex($parser).

GetCurrentByteCount#

GetCurrentByteCount($parser).

GetSpecifiedAttributeCount#

GetSpecifiedAttributeCount($parser).

ErrorString#

ErrorString($code): the message for an error code.

ExpatVersion#

ExpatVersion(): “expat_X.Y.Z”, the interface this module provides.

ExpatVersionInfo#

ExpatVersionInfo(): (major => X, minor => Y, micro => Z).

LoadEncoding#

LoadEncoding($data, $size): register a binary encoding map (an .enc file’s contents) in %Encoding_Table; returns its name, or undef when the data is not a map.

FreeEncoding#

FreeEncoding($encinfo): free a map LoadEncoding made.

OriginalString#

OriginalString($parser): the input text of the current event.

ElementIndex#

ElementIndex($parser): the serial number of the current element.

SkipUntil#

SkipUntil($parser, $index): suspend most handlers until the element with serial number $index starts.

Do_External_Parse#

Do_External_Parse($parser, $result): the ExternEnt handler’s result is read by the loader that called the handler, so outside one there is nothing to parse into.

SetReparseDeferralEnabled#

SetReparseDeferralEnabled($parser, $enabled): expat’s deferral of reparsing a token split across buffers (parse_buffer); XML_TRUE.