X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FHTML%2FString.pm;h=a7bb28a343d525b9486524e305bb6134828f530a;hb=c82dc8d3a3a6c6afd7f8eee2bba39f9063a01c3e;hp=033be4e9516d40248dc21c17549c3eb83a453972;hpb=e1b4b35c28896558b77f9df03dc4fd5561c84ca4;p=scpubgit%2FHTML-String.git

diff --git a/lib/HTML/String.pm b/lib/HTML/String.pm
index 033be4e..a7bb28a 100644
--- a/lib/HTML/String.pm
+++ b/lib/HTML/String.pm
@@ -4,6 +4,10 @@ use strictures 1;
 use HTML::String::Value;
 use Exporter 'import';
 
+our $VERSION = '1.000001'; # 1.0.1
+
+$VERSION = eval $VERSION;
+
 our @EXPORT = qw(html);
 
 sub html {
@@ -11,3 +15,158 @@ sub html {
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+HTML::String - mark strings as HTML to get auto-escaping
+
+=head1 SYNOPSIS
+
+  use HTML::String;
+  
+  my $not_html = 'Hello, Bob & Jake';
+  
+  my $html = html('<h1>').$not_html.html('</h1>');
+  
+  print html($html); # <h1>Hello, Bob &amp; Jake</h1>
+
+or, alternatively,
+
+  use HTML::String::Overload;
+  
+  my $not_html = 'Hello, Bob & Jake';
+  
+  my $html = do {
+    use HTML::String::Overload;
+    "<h1>${not_html}</h1>";
+  }
+  
+  print html($html); # <h1>Hello, Bob &amp; Jake</h1>
+
+(but see the L<HTML::String::Overload> documentation for details and caveats).
+
+See also L<HTML::String::TT> for L<Template Toolkit|Template> integration.
+
+=head1 DESCRIPTION
+
+Tired of trying to remember which strings in your program need HTML escaping?
+
+Working on something small enough to not need a templating engine - or code
+heavy enough to be better done with strings - but wanting to be careful about
+user supplied data?
+
+Yeah, me too, sometimes. So I wrote L<HTML::String>.
+
+The idea here is to have pervasive HTML escaping that fails closed - i.e.
+escapes everything that it isn't explicitly told not to. Since in the era
+of XSS (cross site scripting) attacks it's a matter of security as well as
+of not serving mangled markup, I've preferred to err on the side of
+inconvenience in places in order to make it as hard as possible to screw up.
+
+We export a single subroutine, L</html>, whose sole purpose in life
+is to construct an L<HTML::String::Value> object from a string, which then
+obsessively refuses to be concatenated to anything else without escaping it
+unless you asked for that not to happen by marking the other thing as HTML
+too.
+
+So
+
+  html($thing).$other_thing
+
+will return an object where C<$thing> won't be escaped, but C<$other_thing>
+will. Keeping concatenating stuff is fine; internally it's an array of parts.
+
+Because html() will happily take something that's already wrapped into a
+value object, when we print it out we can do:
+
+  print html($final_result);
+
+safe in the knowledge that if we got passed a value object that won't break
+anything, but if by some combination of alarums, excursions and murphy
+strikes we still have just a plain string by that point, the plain string
+will still get escaped on the way out.
+
+If you've got distinct blocks of code where you're assembling HTML, instead
+of using L</html> a lot you can say "all strings in this block are HTML
+so please mark them all to not be escaped" using L<HTML::String::Overload> -
+
+  my $string = 'This is a "normal" string';
+  
+  my $html;
+  
+  {
+    use HTML::String::Overload; # valid until the end of the block
+
+    $html = '<foo>'.$string.'</foo>'; # the two strings are html()ified
+  }
+
+  print $html; # prints <foo>This is a &quot;normal&quot; string</foo>
+
+Note however that due to a perl bug, you can't use backslash escapes in
+a string and have it still get marked as an HTML value, so instead of
+
+  "<h1>\n<div>"
+
+you need to write
+
+  "<h1>"."\n"."</div>"
+
+at least as far as 5.16.1, which is current as I write this. See
+L<HTML::String::Overload> for more details.
+
+For integration with L<Template Toolkit|Template>, see L<HTML::String::TT>.
+
+=head1 CHARACTERS THAT WILL BE ESCAPED
+
+HTML::String concerns itself with characters that have special meaning in
+HTML. Those which begin and end tags (< and >), those which begin an entity
+(&) and those which delimit attribute values (" and '). It outputs them
+in a fashion compatible with HTML 4 and newer and all versions of XHTML
+(assuming support for named entities in the parser). There are no known
+incompatibilities with browsers. 
+
+HTML::String does not concern itself with other characters, it is assumed
+that HTML documents will be marked with a suitable character encoding via
+a Content-Type HTTP header and/or a meta element.
+
+=head1 EXPORTS
+
+=head2 html
+
+  my $html = html($do_not_escape_this);
+
+Returns an L<HTML::String::Value> object containing a single string part
+marked not to be escaped.
+
+If you need to do something clever such as specifying packages for which
+to ignore escaping requests, see the L<HTML::String::Value> documentation
+and write your own subroutine - this one is as simple as
+
+  sub html {
+    return HTML::String::Value->new($_[0]);
+  }
+
+so providing configuration options would likely be more complicated and
+confusing than just writing the code.
+
+=head1 AUTHOR
+
+mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
+
+=head1 CONTRIBUTORS
+
+dorward - David Dorward (cpan:DORWARD) <david@dorward.me.uk>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2012 the HTML::String L</AUTHOR> and L</CONTRIBUTORS>
+as listed above.
+
+=head1 LICENSE
+
+This library is free software and may be distributed under the same terms
+as perl itself.
+
+=cut