HTML::...ributes(3pm)

💖 HTML::RewriteAttributes 💖

okay bestie, so this is HTML::RewriteAttributes — a Perl module (from the User Contributed Perl Documentation collection, we love a community moment) that does concise attribute rewriting. that's the whole name, that's the whole vibe: you point it at a chunk of HTML, and it goes in and deletes, adds, or rewrites the attributes on the tag you care about. then it hands you back the updated HTML. slay.

---

✨ SYNOPSIS ✨

the whole thing in one breath: locate a tag in a provided block of HTML and delete, add, or rewrite the attributes associated with that tag. the updated HTML is returned. periodt.

🗑️ deleting an attribute

you delete an attribute by returning undef. that's it. that's the move.

$html = HTML::RewriteAttributes->rewrite($html, sub {
    my ($tag, $attr, $value) = @_;

    # delete any attribute that mentions..
    return if $value =~ /COBOL/i;

    $value =~ s/\brocks\b/rules/g;
    return $value;
});

➕ adding an attribute

to add an attribute you append it to the $attr_list arrayref and add the value to the $attrs hashref. both. not one. both. like, for example, you could add loading="lazy" to all img tags:

$html = HTML::RewriteAttributes->rewrite($html, sub {
    my ( $tag, $attr, $value, $attrs, $attr_list ) = @_;
    return $value unless $tag eq 'img' && !$attrs->{loading};
    $attrs->{loading} = 'lazy';
    push @$attr_list, 'loading';
    return $value;
});

✏️ modifying an existing attribute

just return the new value. lowkey the simplest one. the example below would be a src attribute for an img in an email:

$html = HTML::RewriteAttributes::Resources->rewrite($html, sub {
    my $uri = shift;
    my $content = render_template($uri);
    my $cid = generate_cid_from($content);
    $mime->attach($cid => content);
    return "cid:$cid";
});

🔗 links, but make it base-URL-aware

if you pass a URL, HTML::RewriteAttributes::Links can update resources like hrefs or imgs to include the base URL — turning <img src="/bar.gif"> into <img src="https://search.cpan.org/bar.gif">. iconic. also peep HTML::ResolveLink while you're here.

$html = HTML::RewriteAttributes::Links->rewrite($html, "https://search.cpan.org");

# Passing a subroutine reference, L<HTML::RewriteAttributes::Links> can
# extract all links, similar to L<HTML::LinkExtor>.

HTML::RewriteAttributes::Links->rewrite($html, sub {
    my ($tag, $attr, $value) = @_;
    push @links, $value;
    $value;
});

---

🌸 DESCRIPTION 🌸

HTML::RewriteAttributes is designed for simple yet powerful HTML attribute rewriting. it's giving "do one thing and do it gorgeously."

you simply specify a callback to run for each attribute and we do the rest for you. that's the deal. you bring the callback, we bring the entire attribute-walking situation.

this module is designed to be subclassable to make handling special cases easier. see the source for methods you can override. 👑

and yeah — see the SYNOPSIS above and the included tests in the t directory for more examples. the tests are right there, go look, they don't bite.

---

🛠️ METHODS 🛠️

💅 new

you don't need to call new explicitly — it's done in rewrite. it takes no arguments. so like, don't worry about it. it's handled.

💅 rewrite HTML, callback -> HTML

this is the main interface of the module. you pass in some HTML and a callback, the callback is invoked potentially many times, and you get back some similar HTML. (similar!! not identical!! the whole point is that it changed!!)

as rewrite parses the HTML block, it calls the provided callback, passing as arguments the current tag name, the attribute name, and the attribute value — though subclasses may override this, and HTML::RewriteAttributes::Resources does, so heads up. the callback can then use the arguments to determine if you want to change the current tag or attribute, or skip it by returning the current value unchanged. and if you do find the tag and attribute you want to change? return undef to remove the attribute, or any other value to set the value of the attribute.

the callback also is passed a hashref $attrs which has keys for attributes and values with the current values. finally $attr_list is passed as an arrayref containing all attributes for the current tag. so to add a new attribute: add the attribute name to the $attr_list arrayref, and add the new value to $attrs. that's the recipe, bestie, don't freestyle it.

---

👀 SEE ALSO 👀

• HTML::Parser
• HTML::ResolveLink
• Email::MIME::CreateHTML
• HTML::LinkExtor

---

🫶 THANKS 🫶

some code was inspired by, and tests borrowed from, Miyagawa's HTML::ResolveLink. credit where credit is due, we stan. 🌈

---

✍️ AUTHOR ✍️

Best Practical Solutions, LLC <modules@bestpractical.com>

---

📜 LICENSE 📜

Copyright 2008-2024 Best Practical Solutions, LLC.

HTML::RewriteAttributes is distributed under the same terms as Perl itself.

---

ngl the copyright runs 2008-2024 which is a long main-character run, respect.

and that's the page!! this is HTML::...ributes(3pm) from the User Contributed Perl Documentation, version perl v5.40.0, dated 2024-11-15 — mwah, go rewrite some attributes, you've got this 💖✨🎀