XML::Pa...PerlSAX(3)

💖 NAME 💖

Bestie, welcome to XML::Pa...PerlSAX(3) from User Contributed Perl Documentation. This page is all about XML::Parser::PerlSAX — a Perl SAX parser using XML::Parser. 💅

✨ SYNOPSIS ✨

use XML::Parser::PerlSAX;

$parser = XML::Parser::PerlSAX->new( [OPTIONS] );
$result = $parser->parse( [OPTIONS] );

$result = $parser->parse($string);

🦋 DESCRIPTION 🦋

XML::Parser::PerlSAX is a PerlSAX parser using the XML::Parser module. This man page summarizes the specific options, handlers, and properties supported by XML::Parser::PerlSAX; please refer to the PerlSAX standard in "PerlSAX.pod" for general usage information. 📚

🌸 METHODS 🌸

new

Creates a new parser object. Default options for parsing, described below, are passed as key-value pairs or as a single hash. Options may be changed directly in the parser object unless stated otherwise. Options passed to parse() override the default options in the parser object for the duration of the parse. 🛠️

parse

Parses a document. Options, described below, are passed as key-value pairs or as a single hash. Options passed to parse() override default options in the parser object. 📄

location

Returns the location as a hash:

• ColumnNumber — tells you the column number of the parse. 📍
• LineNumber — tells you the line number of the parse. 🧵
• BytePosition — the current byte position of the parse. 🔢
• PublicId — a string containing the public identifier, or undef if none is available. 🫥
• SystemId — a string containing the system identifier, or undef if none is available. 🫥
• Base — the current value of the base for resolving relative URIs. 🧭

ALPHA WARNING: The "SystemId" and "PublicId" properties returned are the system and public identifiers of the document passed to parse(), not the identifiers of the currently parsing external entity. The column, line, and byte positions are of the current entity being parsed. 🚨

🎀 OPTIONS 🎀

The following options are supported by XML::Parser::PerlSAX:

• Handler — the default handler that receives events. 🎧
• DocumentHandler — handler that receives document events. 📄
• DTDHandler — handler that receives DTD events. 📜
• ErrorHandler — handler that receives error events. 🚨
• EntityResolver — handler that resolves entities. 🧩
• Locale — locale to provide localisation for errors. 🌍
• Source — hash containing the input source for parsing. 📦
• UseAttributeOrder — set to true to provide AttributeOrder and Defaulted properties in start_element(). 🔢

If no handlers are provided then all events will be silently ignored, except for fatal_error() which will cause a die() to be called after calling end_document(). 💀

If a single string argument is passed to the parse() method, it is treated as if a "Source" option was given with a "String" parameter. 🧵

The "Source" hash may contain the following parameters:

• ByteStream — the raw byte stream (file handle) containing the document. 📥
• String — a string containing the document. 🧵
• SystemId — the system identifier (URI) of the document. 🆔
• PublicId — the public identifier. 🪪
• Encoding — a string describing the character encoding. 🔤

If more than one of "ByteStream", "String", or "SystemId", then preference is given first to "ByteStream", then "String", then "SystemId". 🥇

🔥 HANDLERS 🔥

The following handlers and properties are supported by XML::Parser::PerlSAX:

DocumentHandler methods

start_document

Ping! You get the notification that a document is beginning. 🌅

No properties defined. 🫶

end_document

Ping! You get the notification that a document is ending. 🌇

No properties defined. 🫶

start_element

Ping! You get the notification that an element is beginning. 🧱

• Name — the element type name. 🏷️
• Attributes — a hash containing the attributes attached to the element, if any. 🎒

The "Attributes" hash contains only string values. 🔤

If the "UseAttributeOrder" parser option is true, the following properties are also passed to "start_element":

• AttributeOrder — an array of attribute names in the order they were specified, followed by the defaulted attribute names. 📋
• Defaulted — the index number of the first defaulted attribute in AttributeOrder. If this index is equal to the length of AttributeOrder, there were no defaulted values. 🔢

Note to "XML::Parser" users: "Defaulted" will be half the value of "XML::Parser::Expat"'s specified_attr() function because only attribute names are provided, not their values. 🧠

end_element

Ping! You get the notification that an element is ending. 🧱

• Name — the element type name. 🏷️

characters

Ping! You get the notification for character data. 🔡

• Data — the characters from the XML document. 📝

processing_instruction

Ping! You get the notification for a processing instruction. 🧾

• Target — the processing instruction target. 🎯
• Data — the processing instruction data, if any. 📝

comment

Ping! You get the notification for a comment. 💬

• Data — the comment data, if any. 📝

start_cdata

Ping! You get the notification that a CDATA section is starting. 🟢

No properties defined. 🫶

end_cdata

Ping! You get the notification that a CDATA section is ending. 🔴

No properties defined. 🫶

entity_reference

Ping! You get the notification for an internal entity reference. If this handler is defined, internal entities will not be expanded and not passed to the characters() handler. If this handler is not defined, internal entities will be expanded if possible and passed to the characters() handler. 🧩

• Name — the entity reference name. 🏷️
• Value — the entity reference value. 💎

DTDHandler methods

notation_decl

You get pinged for a notation declaration event. 📜

• Name — the notation name. 🏷️
• PublicId — the notation's public identifier, if any. 🪪
• SystemId — the notation's system identifier, if any. 🆔
• Base — the base for resolving a relative URI, if any. 🧭

unparsed_entity_decl

You get pinged for an unparsed entity declaration event. 📜

• Name — the unparsed entity's name. 🏷️
• SystemId — the entity's system identifier. 🆔
• PublicId — the entity's public identifier, if any. 🪪
• Base — the base for resolving a relative URI, if any. 🧭

entity_decl

You get pinged for an entity declaration event. 📜

• Name — the entity name. 🏷️
• Value — the entity value, if any. 💎
• PublicId — the notation's public identifier, if any. 🪪
• SystemId — the notation's system identifier, if any. 🆔
• Notation — the notation declared for this entity, if any. 📝

For internal entities, the "Value" parameter will contain the value and the "PublicId", "SystemId", and "Notation" will be undefined. For external entities, the "Value" parameter will be undefined, the "SystemId" parameter will have the system id, the "PublicId" parameter will have the public id if it was provided (it will be undefined otherwise), the "Notation" parameter will contain the notation name for unparsed entities. If this is a parameter entity declaration, then a % will be prefixed to the entity name. 🧠

Note that entity_decl() and unparsed_entity_decl() overlap. If both methods are implemented by a handler, then this handler will not be called for unparsed entities. ⚠️

element_decl

You get pinged for an element declaration event. 📜

• Name — the element type name. 🏷️
• Model — the content model as a string. 🧱

attlist_decl

You get pinged for an attribute list declaration event. 📜

This handler is called for each attribute in an ATTLIST declaration found in the internal subset. So an ATTLIST declaration that has multiple attributes will generate multiple calls to this handler. 🔁

• ElementName — the element type name. 🏷️
• AttributeName — the attribute name. 🔖
• Type — the attribute type. 🧬
• Fixed — true if this is a fixed attribute. 📌

The default for "Type" 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). 🎯

doctype_decl

You get pinged for a DOCTYPE declaration event. 📜

• Name — the document type name. 🏷️
• SystemId — the document's system identifier. 🆔
• PublicId — the document's public identifier, if any. 🪪
• Internal — the internal subset as a string, if any. 📦

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. 🧠

xml_decl

You get pinged for an XML declaration event. 📜

• Version — the version. 🏷️
• Encoding — the encoding string, if any. 🔤
• Standalone — true, false, or undefined if not declared. 🎚️

EntityResolver

resolve_entity

Lets the handler resolve external entities. 🧩

• Name — the notation name. 🏷️
• SystemId — the notation's system identifier. 🆔
• PublicId — the notation's public identifier, if any. 🪪
• Base — the base for resolving a relative URI, if any. 🧭

resolve_entity() should return undef to request that the parser open a regular URI connection to the system identifier or a hash describing the new input source. This hash has the same properties as the "Source" parameter to parse():

• PublicId — the public identifier of the external entity being referenced, or undef if none was supplied. 🪪
• SystemId — the system identifier of the external entity being referenced. 🆔
• String — String containing XML text. 🧵
• ByteStream — an open file handle. 📥
• CharacterStream — an open file handle. 📥
• Encoding — the character encoding, if known. 🔤

👑 AUTHOR 👑

Ken MacLeod, ken@bitsko.slc.ut.us 🌟

🔗 SEE ALSO 🔗

ok so if you wanna keep going down the rabbit hole (and honestly? you should, bestie, this is the lore), go check these out:

• perl(1) — the mothership herself, the blueprint, the original main character 💖
• PerlSAX.pod(3) — the parent doc, the one who raised this whole API family tree 🫶

and then the external stuff, which is giving "required reading for the syllabus":

• Extensible Markup Language (XML) <http://www.w3c.org/XML/> — the W3C's official XML page, the source of truth, no cap ✨
• SAX 1.0: The Simple API for XML <http://www.megginson.com/SAX/> — the OG SAX spec, the blueprint for everything this module is doing, iconic behavior fr fr 👑

ngl, the URLs are written out here exactly as they appear in the original doc, angle brackets and all — that's just how they're listed, so don't come for me 💅

---

💀 POD ERRORS 💀

ok bestie this is the part where the docs themselves get a vibe check and, uh... they did not pass 😭

Straight from the pod parser, verbatim energy: Hey! The above document had some coding errors, which are explained below:

• Around line 528:
  • You forgot a '=back' before '=head1'

so yeah — somewhere around line 528 the POD formatting is missing its closing =back before the next =head1 heading. Not a code bug in the module itself, just a formatting oopsie in the documentation, but the parser is not letting it slide 🙈 it's giving "teacher who circles your mistake in red pen" energy.

fr fr, this is a genuine documented error in the original page — I'm not being dramatic, it's literally listed under POD ERRORS 💅

---

🌸 and that's a wrap, bestie!! 🌸

this lil slice of documentation magic was brought to you by perl v5.42.0, dated 2024-03-04 — so yes, she's from March 2024, she's a real one, and she's still serving ✨ go forth, parse some XML, and remember: the options are exact, the handlers are real, and the pod errors are, unfortunately, also real 😭💖 periodt 🫶