Debian Codegraph @

README

raw
1 NAME
2 HTML::RewriteAttributes - concise attribute rewriting
3
4 SYNOPSIS
5 Locate a tag in a provided block of HTML and delete, add, or rewrite the
6 attributes associated with that tag. The updated HTML is returned.
7
8 Delete an attribute by returning undef.
9
10 $html = HTML::RewriteAttributes->rewrite($html, sub {
11 my ($tag, $attr, $value) = @_;
12
13 # delete any attribute that mentions..
14 return if $value =~ /COBOL/i;
15
16 $value =~ s/\brocks\b/rules/g;
17 return $value;
18 });
19
20 Add an attribute by appending it to the $attr_list arrayref and adding
21 the value to the $attrs hashref. For example, you could add
22 "loading="lazy"" to all "img" tags.
23
24 $html = HTML::RewriteAttributes->rewrite($html, sub {
25 my ( $tag, $attr, $value, $attrs, $attr_list ) = @_;
26 return $value unless $tag eq 'img' && !$attrs->{loading};
27 $attrs->{loading} = 'lazy';
28 push @$attr_list, 'loading';
29 return $value;
30 });
31
32 Modify an existing attribute by returning the new value. The example
33 below would be a "src" attribute for an "img" in an email.
34
35 $html = HTML::RewriteAttributes::Resources->rewrite($html, sub {
36 my $uri = shift;
37 my $content = render_template($uri);
38 my $cid = generate_cid_from($content);
39 $mime->attach($cid => content);
40 return "cid:$cid";
41 });
42
43 Passing a URL, HTML::RewriteAttributes::Links can update resources like
44 "href"s or "img"s to include the base URL, changing "<img
45 src="/bar.gif">" to "<img src="https://search.cpan.org/bar.gif">". See
46 also HTML::ResolveLink.
47
48 $html = HTML::RewriteAttributes::Links->rewrite($html, "https://search.cpan.org");
49
50 # Passing a subroutine reference, L<HTML::RewriteAttributes::Links> can
51 # extract all links, similar to L<HTML::LinkExtor>.
52
53 HTML::RewriteAttributes::Links->rewrite($html, sub {
54 my ($tag, $attr, $value) = @_;
55 push @links, $value;
56 $value;
57 });
58
59 DESCRIPTION
60 "HTML::RewriteAttributes" is designed for simple yet powerful HTML
61 attribute rewriting.
62
63 You simply specify a callback to run for each attribute and we do the
64 rest for you.
65
66 This module is designed to be subclassable to make handling special
67 cases easier. See the source for methods you can override.
68
69 See the SYNOPSIS above and included tests in the "t" directory for more
70 examples.
71
72 METHODS
73 "new"
74 You don't need to call "new" explicitly - it's done in "rewrite". It
75 takes no arguments.
76
77 "rewrite" HTML, callback -> HTML
78 This is the main interface of the module. You pass in some HTML and a
79 callback, the callback is invoked potentially many times, and you get
80 back some similar HTML.
81
82 As "rewrite" parses the HTML block, it calls the provided callback,
83 passing as arguments the current tag name, the attribute name, and the
84 attribute value (though subclasses may override this --
85 HTML::RewriteAttributes::Resources does). The callback can then use the
86 arguments to determine if you want to change the current tag or
87 attribute, or skip it by returning the current value unchanged. If you
88 find the tag and attribute you want to change, return "undef" to remove
89 the attribute, or any other value to set the value of the attribute.
90
91 The callback also is passed a hashref $attrs which has keys for
92 attributes and values with the current values. Finally $attr_list is
93 passed as an arrayref contain all attributes for the current tag. To add
94 a new attribute, add the attribute name to the $attr_list arrayref, and
95 add the new value to $attrs.
96
97 SEE ALSO
98 HTML::Parser, HTML::ResolveLink, Email::MIME::CreateHTML,
99 HTML::LinkExtor
100
101 THANKS
102 Some code was inspired by, and tests borrowed from, Miyagawa's
103 HTML::ResolveLink.
104
105 AUTHOR
106 Best Practical Solutions, LLC <[email protected]>
107
108 LICENSE
109 Copyright 2008-2024 Best Practical Solutions, LLC.
110 HTML::RewriteAttributes is distributed under the same terms as Perl
111 itself.
112