```{index} single: XML::Parser::Expat ``` # XML::Parser::Expat ```{pperl-module-badges} XML::Parser::Expat ``` `XML::Parser::Expat` - the low-level interface to the Expat XML parser that `XML::Parser` is built on. ```perl 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('hello'); ``` 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)`.