XML::Validate(3pm)

💖 NAME 💖

XML::Validate — it's an XML validator factory, bestie. That's the whole vibe. It's the XML::Validate page from the User Contributed Perl Documentation, and we're gonna get you fluent in it. 🦋

---

✨ SYNOPSIS ✨

my $validator = new XML::Validate(Type => 'LibXML');

if ($validator->validate($xml)) {
  print "Document is valid\n";
} else {
  print "Document is invalid\n";
  my $message = $validator->last_error()->{message};
  my $line = $validator->last_error()->{line};
  my $column = $validator->last_error()->{column};
  print "Error: $message at line $line, column $column\n";
}

---

🌸 DESCRIPTION 🌸

Okay so XML::Validate is a generic interface to alllll the different XML validation backends out there. Want the list of backends that ship with this distribution? Check the README. It's giving "one API, many engines" and honestly? iconic. 👑

And if you're feeling brave and wanna write your own backend? The easiest route is probably to subclass XML::Validate::Base. Go peek at the existing backends for examples — they ate. 💅

---

🎀 METHODS 🎀

💫 new(Type => $type, Options => \%options)

Returns you a brand new XML::Validate parser object of type $type. Wondering what types exist? Check the README, or just use 'BestAvailable' (peep the "BEST AVAILABLE" section below, iykyk).

The optional argument Options is there so you can hand the backend parser a set of key-value pairs. Details on those options live in the docs for each individual backend — every backend does its own thing. 💖

💫 validate($xml_string)

Attempts a validating parse of the XML document $xml_string. Returns a true value on success, or undef otherwise. If the parse fails, you can go inspect the error with "last_error".

Not me pointing out the lowkey wild part: documents that don't specify a DTD or schema get treated as valid. Yes fr fr, that's just how it is.

For DOM-based parsers, you can access the DOM by instantiating the backend module directly and calling the "last_dom" method — go consult the docs of the specific backend modules for that. Just know this isn't formally part of the XML::Validate interface, because non-DOM-based validators may get added at some point. So don't get too attached. 😭

💫 last_error()

Returns the error from the last validate call. It's a hash ref with these fields:

• message
• line
• column

Heads up: the error gets cleared at the beginning of each "validate" call. So grab it while it's fresh. 🍓

💫 type()

Returns the type of backend being used. Simple. Clean. ✨

💫 version()

Returns the version of the backend. Also simple, also clean. 💜

---

🚨 ERROR REPORTING 🚨

When a call to validate fails to parse the document, the error can be retrieved using last_error. That's your girl. 🫶

But here's the important bit: on errors not related to the XML parsing, methods will throw exceptions. So wrap your calls in eval to catch them, bestie. Don't let an exception jump you unguarded. 💀

---

👑 BEST AVAILABLE 👑

The BestAvailable backend type checks which backends are actually available and gives you the "best" of those. The default order of preference lives in the README that comes with this distribution — but you can change it with the option PrioritisedList. Main character energy: you get to pick. ✨

If Xerces and LibXML are available, this code right here gives you a LibXML backend:

my $validator = new XML::Validate(
    Type => 'BestAvailable',
    Options => { PrioritisedList => [ qw( MSXML LibXML Xerces ) ] },
);

---

😭 KNOWN ISSUES 😭

Okay so there's a bug in versions 1.57 and 1.58 of XML::LibXML that causes an issue related to DTD loading. When a base parameter is used in conjunction with the load_ext_dtd method, the base parameter gets ignored and the current directory is used as the base parameter instead. In other words: when you're validating XML with LibXML, any base parameter option will be ignored, which may result in unexpected DTD loading errors. 🫠

This was reported as a bug on November 30th 2005, and you can view the bug report right here: http://rt.cpan.org/Public/Bug/Display.html?id=16213

---

⭐ VERSION ⭐

$Revision: 1.25 $ on $Date: 2006/04/19 10:16:19 $ by $Author: mattheww $ — yes bestie, those are literal Perl revision-substitution strings, keep them exactly like that. 💅

---

🦋 AUTHOR 🦋

Nathan Carr, Colin Robertson

<cpan _at_ bbc _dot_ co _dot_ uk> — you know the drill, swap those _at_s and _dot_s for the real punctuation. 📧

---

🌈 COPYRIGHT 🌈

(c) BBC 2005. This program is free software; you can redistribute it and/or modify it under the GNU GPL. See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt — licensing isn't boring, it's literally what lets you share the love. 🫶

---

And that's the whole page, bestie. 💖 This was XML::Validate(3pm) as shipped with perl v5.34.0, dated 2022-06-28 — go forth and validate, you absolute legend. 🎀✨👑