XML::D...lParser(3pm)

💖 XML::DOM::ValParser(3pm) 💖

okay so bestie, this is a page from the User Contributed Perl Documentation, and honestly? it's a whole vibe. let's get into it 🫶

---

✨ NAME ✨

XML::DOM::ValParser — it's an XML::DOM::Parser that validates at parse time. like, it checks your XML's whole fit WHILE it's reading it. no cap. 👑

---

🌸 SYNOPSIS 🌸

use XML::DOM::ValParser;

my %expat_options = (KeepCDATA => 1,
                     Handlers => [ Unparsed => \&my_Unparsed_handler ]);
my $parser = new XML::DOM::ValParser (%expat_options);

eval {
    local $XML::Checker::FAIL = \&my_fail;
    my $doc = $parser->parsefile ("fail.xml");
    ... XML::DOM::Document was created successfully ...
};
if ($@) {
    # Either XML::Parser (expat) threw an exception or my_fail() died.
    ... your error handling code here ...
    # Note that the XML::DOM::Document is automatically disposed off and
    # will be garbage collected
}

# Throws an exception (with die) when an error is encountered, this
# will stop the parsing process.
# Don't die if a warning or info message is encountered, just print a message.
sub my_fail {
    my $code = shift;
    die XML::Checker::error_string ($code, @_) if $code < 200;
    XML::Checker::print_error ($code, @_);
}

see how it's wrapped in an eval? that's the move, because parsing can absolutely throw hands 😭

---

💅 DESCRIPTION 💅

Use XML::DOM::ValParser literally anywhere you'd use XML::DOM::Parser, and your XML is gonna get checked with XML::Checker at parse time. that's it, that's the pitch ✨

• For the deets on XML::DOM::Parser options, go peek at XML::DOM. 📚
• For the deets on setting the fail handler (that's my_fail, yes) go peek at XML::Checker. 🎀

the following handlers are currently supported, and they work just like in XML::DOM::Parser:

Init, Final, Char, Start, End, Default, Doctype, CdataStart, CdataEnd, XMLDecl, Entity, Notation, Proc, Default, Comment, Attlist, Element, Unparsed.

not me pointing out that Default shows up twice in that list — that's just how the original rolls, and I am NOT touching it 💀

---

👑 XML::DOM::ValParser 👑

XML::DOM::ValParser extends from XML::Checker::Parser. the way that it works is: it makes an XML::Checker object and routes all the event handlers through the checker, and only then processes the events to build the XML::DOM::Document. so the checking happens before the building, periodt. 🧚

just like XML::Checker::Parser, you can grab the checker object with the getChecker() method and reuse it later on — provided that the DOCTYPE section of the XML::DOM::Document didn't change in the meantime. iykyk 🌸

you get to control which errors are fatal (and therefore should stop the creation of the XML::DOM::Document) by filtering the appropriate error codes in the global $XML::Checker::FAIL handler (see "ERROR_HANDLING" in XML::Checker) and calling die or croak appropriately. so dramatic, so powerful 💅

and just like XML::Checker::Parser, XML::DOM::ValParser supports the SkipExternalDTD and SkipInsignifWS options. see XML::Checker::Parser for the details. 🔥

---

🦋 AUTHOR 🦋

Enno Derksen is the original author. 👑

send bug reports, hints, tips, suggestions to T.J. Mather at <tjmather@tjmather.com>. 🫶

---

🌈 SEE ALSO 🌈

• XML::DOM
• XML::Checker ("SEE_ALSO" in XML::Checker)

---

and that's the whole page, bestie!! this one shipped as perl v5.34.0, dated 2022-06-28, in the User Contributed Perl Documentation. slay, stay valid, and validate your XML at parse time 💖✨🎀