4 use HTML::String::Value;
7 our $VERSION = '1.000003'; # 1.0.3
9 $VERSION = eval $VERSION;
11 our @EXPORT = qw(html);
14 HTML::String::Value->new($_[0]);
23 HTML::String - mark strings as HTML to get auto-escaping
29 my $not_html = 'Hello, Bob & Jake';
31 my $html = html('<h1>').$not_html.html('</h1>');
33 print html($html); # <h1>Hello, Bob & Jake</h1>
37 use HTML::String::Overload;
39 my $not_html = 'Hello, Bob & Jake';
42 use HTML::String::Overload;
43 "<h1>${not_html}</h1>";
46 print html($html); # <h1>Hello, Bob & Jake</h1>
48 (but see the L<HTML::String::Overload> documentation for details and caveats).
50 See also L<HTML::String::TT> for L<Template Toolkit|Template> integration.
54 Tired of trying to remember which strings in your program need HTML escaping?
56 Working on something small enough to not need a templating engine - or code
57 heavy enough to be better done with strings - but wanting to be careful about
60 Yeah, me too, sometimes. So I wrote L<HTML::String>.
62 The idea here is to have pervasive HTML escaping that fails closed - i.e.
63 escapes everything that it isn't explicitly told not to. Since in the era
64 of XSS (cross site scripting) attacks it's a matter of security as well as
65 of not serving mangled markup, I've preferred to err on the side of
66 inconvenience in places in order to make it as hard as possible to screw up.
68 We export a single subroutine, L</html>, whose sole purpose in life
69 is to construct an L<HTML::String::Value> object from a string, which then
70 obsessively refuses to be concatenated to anything else without escaping it
71 unless you asked for that not to happen by marking the other thing as HTML
76 html($thing).$other_thing
78 will return an object where C<$thing> won't be escaped, but C<$other_thing>
79 will. Keeping concatenating stuff is fine; internally it's an array of parts.
81 Because html() will happily take something that's already wrapped into a
82 value object, when we print it out we can do:
84 print html($final_result);
86 safe in the knowledge that if we got passed a value object that won't break
87 anything, but if by some combination of alarums, excursions and murphy
88 strikes we still have just a plain string by that point, the plain string
89 will still get escaped on the way out.
91 If you've got distinct blocks of code where you're assembling HTML, instead
92 of using L</html> a lot you can say "all strings in this block are HTML
93 so please mark them all to not be escaped" using L<HTML::String::Overload> -
95 my $string = 'This is a "normal" string';
100 use HTML::String::Overload; # valid until the end of the block
102 $html = '<foo>'.$string.'</foo>'; # the two strings are html()ified
105 print $html; # prints <foo>This is a "normal" string</foo>
107 Note however that due to a perl bug, you can't use backslash escapes in
108 a string and have it still get marked as an HTML value, so instead of
116 at least as far as 5.16.1, which is current as I write this. See
117 L<HTML::String::Overload> for more details.
119 For integration with L<Template Toolkit|Template>, see L<HTML::String::TT>.
121 =head1 CHARACTERS THAT WILL BE ESCAPED
123 HTML::String concerns itself with characters that have special meaning in
124 HTML. Those which begin and end tags (< and >), those which begin an entity
125 (&) and those which delimit attribute values (" and '). It outputs them
126 in a fashion compatible with HTML 4 and newer and all versions of XHTML
127 (assuming support for named entities in the parser). There are no known
128 incompatibilities with browsers.
130 HTML::String does not concern itself with other characters, it is assumed
131 that HTML documents will be marked with a suitable character encoding via
132 a Content-Type HTTP header and/or a meta element.
138 my $html = html($do_not_escape_this);
140 Returns an L<HTML::String::Value> object containing a single string part
141 marked not to be escaped.
143 If you need to do something clever such as specifying packages for which
144 to ignore escaping requests, see the L<HTML::String::Value> documentation
145 and write your own subroutine - this one is as simple as
148 return HTML::String::Value->new($_[0]);
151 so providing configuration options would likely be more complicated and
152 confusing than just writing the code.
156 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
160 dorward - David Dorward (cpan:DORWARD) <david@dorward.me.uk>
161 rafl - Florian Ragwitz (cpan:FLORA) <rafl@debian.org>
165 Copyright (c) 2012 the HTML::String L</AUTHOR> and L</CONTRIBUTORS>
170 This library is free software and may be distributed under the same terms