XML::Parser::Expat#

📦 max

XML::Parser::Expat - the low-level interface to the Expat XML parser that XML::Parser is built on.

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 the system’s libexpat, loaded when the module is first used: libexpat 2.6.0 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; its XML/Parser.pm, XML/Parser/Expat.pm and the XML::Parser::Style::* modules are used unchanged.

Differences from upstream#

The protection limits are there whenever the installed libexpat has them: SetBillionLaughsAttackProtectionMaximumAmplification, SetBillionLaughsAttackProtectionActivationThreshold (libexpat 2.4+) and SetAllocTrackerMaximumAmplification, SetAllocTrackerActivationThreshold (2.7.2+). The XS module decides this when it is compiled, from libexpat build options a program using libexpat cannot see, and commonly leaves all four out even where the library provides them (perl 5.44 with XML-Parser 2.59 against libexpat 2.8.5 has none of them).

Functions#

Other Functions#

ParserCreate#

ParserCreate($self, $encoding, $namespaces): a new expat 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.

SetStartElementHandler#

SetStartElementHandler($parser, $handler); returns the old one.

SetEndElementHandler#

SetEndElementHandler($parser, $handler); returns the old one.

SetCharacterDataHandler#

SetCharacterDataHandler($parser, $handler); returns the old one.

SetProcessingInstructionHandler#

SetProcessingInstructionHandler($parser, $handler).

SetCommentHandler#

SetCommentHandler($parser, $handler).

SetDefaultHandler#

SetDefaultHandler($parser, $handler): with NoExpand, internal entity references reach the handler unexpanded.

SetUnparsedEntityDeclHandler#

SetUnparsedEntityDeclHandler($parser, $handler).

SetNotationDeclHandler#

SetNotationDeclHandler($parser, $handler).

SetExternalEntityRefHandler#

SetExternalEntityRefHandler($parser, $handler); the C handler stays installed for implicit parameter-entity parsing.

SetExtEntFinishHandler#

SetExtEntFinishHandler($parser, $handler): called after an external entity was parsed (expat has no such handler).

SetEntityDeclHandler#

SetEntityDeclHandler($parser, $handler).

SetElementDeclHandler#

SetElementDeclHandler($parser, $handler).

SetAttListDeclHandler#

SetAttListDeclHandler($parser, $handler).

SetDoctypeHandler#

SetDoctypeHandler($parser, $handler); the C handler always stays, for the DOCTYPE system id.

SetEndDoctypeHandler#

SetEndDoctypeHandler($parser, $handler).

SetXMLDeclHandler#

SetXMLDeclHandler($parser, $handler).

SetStartCdataHandler#

SetStartCdataHandler($parser, $handler).

SetEndCdataHandler#

SetEndCdataHandler($parser, $handler).

UnsetAllHandlers#

UnsetAllHandlers($parser).

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(): the libexpat version string, “expat_X.Y.Z”.

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): parse an external entity from what the ExternEnt handler returned - a handle object, a glob, a reference to one, or the entity’s text.

SetAllocTrackerMaximumAmplification#

SetAllocTrackerMaximumAmplification($parser, $amp).

SetAllocTrackerActivationThreshold#

SetAllocTrackerActivationThreshold($parser, $bytes).

SetReparseDeferralEnabled#

SetReparseDeferralEnabled($parser, $enabled).