lib/HTML/String.pm

   1 package HTML::String;
   2
   3 use strictures 1;
   4 use HTML::String::Value;
   5 use Exporter 'import';
   6
   7 our $VERSION = '1.000006'; # 1.0.6
   8
   9 $VERSION = eval $VERSION;
  10
  11 our @EXPORT = qw(html);
  12
  13 sub html {
  14   HTML::String::Value->new($_[0]);
  15 }
  16
  17 1;
  18
  19 __END__
  20
  21 =head1 NAME
  22
  23 HTML::String - mark strings as HTML to get auto-escaping
  24
  25 =head1 SYNOPSIS
  26
  27   use HTML::String;
  28
  29   my $not_html = 'Hello, Bob & Jake';
  30
  31   my $html = html('<h1>').$not_html.html('</h1>');
  32
  33   print html($html); # <h1>Hello, Bob &amp; Jake</h1>
  34
  35 or, alternatively,
  36
  37   use HTML::String::Overload;
  38
  39   my $not_html = 'Hello, Bob & Jake';
  40
  41   my $html = do {
  42     use HTML::String::Overload;
  43     "<h1>${not_html}</h1>";
  44   }
  45
  46   print html($html); # <h1>Hello, Bob &amp; Jake</h1>
  47
  48 (but see the L<HTML::String::Overload> documentation for details and caveats).
  49
  50 See also L<HTML::String::TT> for L<Template Toolkit|Template> integration.
  51
  52 =head1 DESCRIPTION
  53
  54 Tired of trying to remember which strings in your program need HTML escaping?
  55
  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
  58 user supplied data?
  59
  60 Yeah, me too, sometimes. So I wrote L<HTML::String>.
  61
  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.
  67
  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
  72 too.
  73
  74 So
  75
  76   html($thing).$other_thing
  77
  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.
  80
  81 Because html() will happily take something that's already wrapped into a
  82 value object, when we print it out we can do:
  83
  84   print html($final_result);
  85
  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.
  90
  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> -
  94
  95   my $string = 'This is a "normal" string';
  96
  97   my $html;
  98
  99   {
 100     use HTML::String::Overload; # valid until the end of the block
 101
 102     $html = '<foo>'.$string.'</foo>'; # the two strings are html()ified
 103   }
 104
 105   print $html; # prints <foo>This is a &quot;normal&quot; string</foo>
 106
 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
 109
 110   "<h1>\n<div>"
 111
 112 you need to write
 113
 114   "<h1>"."\n"."</div>"
 115
 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.
 118
 119 For integration with L<Template Toolkit|Template>, see L<HTML::String::TT>.
 120
 121 =head1 CHARACTERS THAT WILL BE ESCAPED
 122
 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.
 129
 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.
 133
 134 =head1 EXPORTS
 135
 136 =head2 html
 137
 138   my $html = html($do_not_escape_this);
 139
 140 Returns an L<HTML::String::Value> object containing a single string part
 141 marked not to be escaped.
 142
 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
 146
 147   sub html {
 148     return HTML::String::Value->new($_[0]);
 149   }
 150
 151 so providing configuration options would likely be more complicated and
 152 confusing than just writing the code.
 153
 154 =head1 AUTHOR
 155
 156 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 157
 158 =head1 CONTRIBUTORS
 159
 160 dorward - David Dorward (cpan:DORWARD) <david@dorward.me.uk>
 161 rafl - Florian Ragwitz (cpan:FLORA) <rafl@debian.org>
 162
 163 =head1 COPYRIGHT
 164
 165 Copyright (c) 2012 the HTML::String L</AUTHOR> and L</CONTRIBUTORS>
 166 as listed above.
 167
 168 =head1 LICENSE
 169
 170 This library is free software and may be distributed under the same terms
 171 as perl itself.
 172
 173 =cut