4 use HTML::String::Value;
7 our $VERSION = '1.000000'; # 1.0.0
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>.
125 my $html = html($do_not_escape_this);
127 Returns an L<HTML::String::Value> object containing a single string part
128 marked not to be escaped.
130 If you need to do something clever such as specifying packages for which
131 to ignore escaping requests, see the L<HTML::String::Value> documentation
132 and write your own subroutine - this one is as simple as
135 return HTML::String::Value->new($_[0]);
138 so providing configuration options would likely be more complicated and
139 confusing than just writing the code.
143 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
147 None yet - maybe this software is perfect! (ahahahahahahahahaha)
151 Copyright (c) 2012 the HTML::String L</AUTHOR> and L</CONTRIBUTORS>
156 This library is free software and may be distributed under the same terms