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 @EXPORT = qw(html);
   8
   9 sub html {
  10   HTML::String::Value->new($_[0]);
  11 }
  12
  13 1;
  14
  15 __END__
  16
  17 =head1 NAME
  18
  19 HTML::String - mark strings as HTML to get auto-escaping
  20
  21 =head1 SYNOPSIS
  22
  23   use HTML::String;
  24
  25   my $not_html = 'Hello, Bob & Jake';
  26
  27   my $html = html('<h1>').$not_html.html('</h1>');
  28
  29   print html($html); # <h1>Hello, Bob &quot; Jake</h1>
  30
  31 or, alternatively,
  32
  33   use HTML::String::Overload;
  34
  35   my $not_html = 'Hello, Bob & Jake';
  36
  37   my $html = do {
  38     use HTML::String::Overload;
  39     "<h1>${not_html}</h1>";
  40   }
  41
  42   print html($html); # <h1>Hello, Bob &quot; Jake</h1>
  43
  44 (but see the L<HTML::String::Overload> documentation for details and caveats).
  45
  46 See also L<HTML::String::TT> for L<Template Toolkit|Template> integration.
  47
  48 =head1 DESCRIPTION
  49
  50 Tired of trying to remember which strings in your program need HTML escaping?
  51
  52 Working on something small enough to not need a templating engine - or code
  53 heavy enough to be better done with strings - but wanting to be careful about
  54 user supplied data?
  55
  56 Yeah, me too, sometimes. So I wrote L<HTML::String>.
  57
  58 The idea here is to have pervasive HTML escaping that fails closed - i.e.
  59 escapes everything that it isn't explicitly told not to. Since in the era
  60 of XSS (cross site scripting) attacks it's a matter of security as well as
  61 of not serving mangled markup, I've preferred to err on the side of
  62 inconvenience in places in order to make it as hard as possible to screw up.
  63
  64 We export a single subroutine, L</html>, whose sole purpose in life
  65 is to construct an L<HTML::String::Value> object from a string, which then
  66 obsessively refuses to be concatenated to anything else without escaping it
  67 unless you asked for that not to happen by marking the other thing as HTML
  68 too.
  69
  70 So
  71
  72   html($thing).$other_thing
  73
  74 will return an object where C<$thing> won't be escaped, but C<$other_thing>
  75 will. Keeping concatenating stuff is fine; internally it's an array of parts.
  76
  77 Because html() will happily take something that's already wrapped into a
  78 value object, when we print it out we can do:
  79
  80   print html($final_result);
  81
  82 safe in the knowledge that if we got passed a value object that won't break
  83 anything, but if by some combination of alarums, excursions and murphy
  84 strikes we still have just a plain string by that point, the plain string
  85 will still get escaped on the way out.
  86
  87 If you've got distinct blocks of code where you're assembling HTML, instead
  88 of using L</html> a lot you can say "all strings in this block are HTML
  89 so please mark them all to not be escaped" using L<HTML::String::Overload> -
  90
  91   my $string = 'This is a "normal" string';
  92
  93   my $html;
  94
  95   {
  96     use HTML::String::Overload; # valid until the end of the block
  97
  98     $html = '<foo>'.$string.'</foo>'; # the two strings are html()ified
  99   }
 100
 101   print $html; # prints <foo>This is a &quot;normal&quot; string</foo>
 102
 103 Note however that due to a perl bug, you can't use backslash escapes in
 104 a string and have it still get marked as an HTML value, so instead of
 105
 106   "<h1>\n<div>"
 107
 108 you need to write
 109
 110   "<h1>"."\n"."</div>"
 111
 112 at least as far as 5.16.1, which is current as I write this. See
 113 L<HTML::String::Overload> for more details.
 114
 115 For integration with L<Template Toolkit|Template>, see L<HTML::String::TT>.
 116
 117 =head1 EXPORTS
 118
 119 =head2 html
 120
 121   my $html = html($do_not_escape_this);
 122
 123 Returns an L<HTML::String::Value> object containing a single string part
 124 marked not to be escaped.
 125
 126 If you need to do something clever such as specifying packages for which
 127 to ignore escaping requests, see the L<HTML::String::Value> documentation
 128 and write your own subroutine - this one is as simple as
 129
 130   sub html {
 131     return HTML::String::Value->new($_[0]);
 132   }
 133
 134 so providing configuration options would likely be more complicated and
 135 confusing than just writing the code.
 136
 137 =head1 AUTHOR
 138
 139 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 140
 141 =head1 CONTRIBUTORS
 142
 143 None yet - maybe this software is perfect! (ahahahahahahahahaha)
 144
 145 =head1 COPYRIGHT
 146
 147 Copyright (c) 2012 the HTML::String L</AUTHOR> and L</CONTRIBUTORS>
 148 as listed above.
 149
 150 =head1 LICENSE
 151
 152 This library is free software and may be distributed under the same terms
 153 as perl itself.
 154
 155 =cut