HTML::...:Sanity(3pm)

💖 HTML::HTML5::Sanity 💖

okay bestie, so this is a page from the User Contributed Perl Documentation, and it's all about HTML::...:Sanity(3pm) — a lil module that takes your HTML5 DOM tree and makes it... less feral. 🧚

---

✨ NAME ✨

HTML::HTML5::Sanity — make HTML5 DOM trees less insane 🫶

---

🌸 SYNOPSIS 🌸

use HTML::HTML5::Parser;
use HTML::HTML5::Sanity;

my $parser    = HTML::HTML5::Parser->new;
my $html5_dom = $parser->parse_file('http://example.com/');
my $sane_dom  = fix_document($html5_dom);

---

💅 DESCRIPTION 💅

So the Document Object Model (DOM) that HTML::HTML5::Parser hands you? It fully meets the requirements of the HTML5 spec, no cap. But it will probably catch a lot of people by surprise. It's giving "technically correct but emotionally devastating." 😭

The main oddity — the big one, the moment — is that elements and attributes which appear to be namespaced? They are not really. Like, look at this element:

<div xml:lang="fr">...</div>

You'd think it should be parsed so it has an attribute lang in the XML namespace, right? Yeah. Not so. It will really be parsed as having the attribute xml:lang in the null namespace. That's just what's happening. It's iconic in a cursed way. 💀

---

fix_document($document)

$sane_dom = fix_document($html5_dom);

Returns a modified copy of the DOM, and leaves the original DOM unmodified. Your original stays untouched, bestie, we're not like that. 🎀

---

fix_element($element_node, $new_document_node, \%namespaces)

Don't use this. Not exported. 🙈

---

fix_attribute($attribute_node, $new_element_node, \%namespaces)

Don't use this. Not exported. 🙈

---

$HTML::HTML5::Sanity::FIX_LANG_ATTRIBUTES

$HTML::HTML5::Sanity::FIX_LANG_ATTRIBUTES = 2;
$sane_dom = fix_document($html5_dom);

This is your vibe check for language attributes, and here's the tea:

• Set it to 1 (which is the default), and the package will detect invalid values in @lang and @xml:lang, and remove the attribute if it is invalid. bye girl 👋
• Set it to 2, and it will also attempt to canonicalise the value (e.g. 'EN_GB' will be converted to to 'en-GB'). glow up ✨
• Set it to 0, and then the value of language attributes is not checked. at all. no thoughts, head empty. 🦋

---

🐛 BUGS 🐛

Please report any bugs to <http://rt.cpan.org/>. fr fr, they wanna hear it. 💜

---

👀 SEE ALSO 👀

HTML::HTML5::Parser, XML::LibXML, Task::HTML5.

---

👑 AUTHOR 👑

Toby Inkster <tobyink@cpan.org>.

---

🌈 COPYRIGHT AND LICENSE 🌈

Copyright (C) 2009-2014 by Toby Inkster

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

💀 DISCLAIMER OF WARRANTIES 💀

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

okay so this one is in all caps for a reason, bestie — no promises, no guarantees, that's the whole point. 🙏

---

and that's the whole page, periodt. this little number shipped as perl v5.34.0, dated 2022-07-11, and it lives in the man pages as HTML::...:Sanity(3pm). go forth and fix those documents, you absolute main character 🫶💖