Release commit for 1.000006

[scpubgit/HTML-String.git] / lib / HTML / String / Overload.pm

diff --git a/lib/HTML/String/Overload.pm b/lib/HTML/String/Overload.pm
index 3c72850..ece0d15 100644 (file)
--- a/lib/HTML/String/Overload.pm
+++ b/lib/HTML/String/Overload.pm
@@ -18,3 +18,70 @@ sub unimport {
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+HTML::String::Overload - Use constant overloading with L<HTML::String>
+
+=head1 SYNOPSIS
+
+  use HTML::String::Overload;
+  
+  my $html = '<h1>'; # marked as HTML
+  
+  no HTML::String::Overload;
+
+  my $text = '<h1>'; # not touched
+  
+  my $html = do {
+    use HTML::String::Overload;
+  
+    '<h1>'; # marked as HTML
+  };
+  
+  my $text = '<h1>'; # not touched
+
+=head1 DESCRIPTION
+
+This module installs a constant overload for strings - see
+L<overload/Overloading constants> in overload.pm's docs for how that works.
+
+On import, we both set up the overload, and use L<B::Hooks::EndOfScope> to
+register a callback that will remove it again at the end of the block; you
+can remove it earlier by unimporting the module using C<no>.
+
+=head1 CAVEATS
+
+Due to a perl bug (L<https://rt.perl.org/rt3/Ticket/Display.html?id=49594>),
+you can't use backslash escapes in a string to be marked as HTML, so
+
+  use HTML::String::Overload;
+  
+  my $html = "<h1>\n<div>foo</div>\n</h1>";
+
+will not be marked as HTML - instead you need to write
+
+  my $html = '<h1>'."\n".'<div>foo</div>'."\n".'</h1>';
+
+which is annoying, so consider just using L<HTML::String> and doing
+
+  my $html = html("<h1>\n<div>foo</div>\n</h1>");
+
+in that case.
+
+The import method we provide does actually take extra options for constructing
+your L<HTML::String::Value> objects but I'm not yet convinced that's a correct
+public API, so use that feature at your own risk (the only example of this is
+in L<HTML::String::TT::Directive>, which is definitely not user serviceable).
+
+=head1 AUTHORS
+
+See L<HTML::String> for authors.
+
+=head1 COPYRIGHT AND LICENSE
+
+See L<HTML::String> for the copyright and license.
+
+=cut