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.000000'; # 1.0.0
   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 &quot; 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 &quot; 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 EXPORTS
 122
 123 =head2 html
 124
 125   my $html = html($do_not_escape_this);
 126
 127 Returns an L<HTML::String::Value> object containing a single string part
 128 marked not to be escaped.
 129
 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
 133
 134   sub html {
 135     return HTML::String::Value->new($_[0]);
 136   }
 137
 138 so providing configuration options would likely be more complicated and
 139 confusing than just writing the code.
 140
 141 =head1 AUTHOR
 142
 143 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 144
 145 =head1 CONTRIBUTORS
 146
 147 None yet - maybe this software is perfect! (ahahahahahahahahaha)
 148
 149 =head1 COPYRIGHT
 150
 151 Copyright (c) 2012 the HTML::String L</AUTHOR> and L</CONTRIBUTORS>
 152 as listed above.
 153
 154 =head1 LICENSE
 155
 156 This library is free software and may be distributed under the same terms
 157 as perl itself.
 158
 159 =cut