X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FHTML%2FString%2FTT%2FDirective.pm;h=c28ae28fd215095357d4d2c3d868a3781a50ad3a;hb=d86bdf828539c046cbc09d5073897bf24862c93d;hp=770f5fad63dc21fc7bce2b60441e94d5e200dac9;hpb=f554c1ff24bd5a20ea729de4d5456c45fa0ee6ae;p=scpubgit%2FHTML-String.git

diff --git a/lib/HTML/String/TT/Directive.pm b/lib/HTML/String/TT/Directive.pm
index 770f5fa..c28ae28 100644
--- a/lib/HTML/String/TT/Directive.pm
+++ b/lib/HTML/String/TT/Directive.pm
@@ -30,3 +30,69 @@ sub text {
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+HTML::String::TT::Directive - L<Template::Directive> overrides to forcibly escape HTML strings
+
+=head1 SYNOPSIS
+
+This is not user serviceable, and is documented only for your edification.
+
+Please use L<HTML::String::TT> as this module could change, be renamed, or
+if I figure out a better way of implementing the functionality disappear
+entirely at any moment.
+
+=head1 METHODS
+
+=head2 template
+
+We override this top-level method in order to pretend two things to the
+perl subroutine definition that TT has generated - firstly,
+
+  package HTML::String::TT::_TMPL;
+
+to ensure that no packages marked to be ignored are the current one when
+the template code is executed. Secondly,
+
+  use HTML::String::Overload { ignore => { ... } };
+
+where the C<...> contains a list of TT internal packages to ignore so that
+things actually work. This list is not duplicated here since it may also
+change without warning.
+
+Additionally, the hashref option to L<HTML::String::Overload> is not
+documented there since I'm not yet convinced that's a public API either.
+
+=head2 text
+
+Due to a perl bug (L<https://rt.perl.org/rt3/Ticket/Display.html?id=49594>)
+we overload this method to change
+
+  "<foo>\n<bar>"
+
+into
+
+  "<foo>"."\n"."<bar>"
+
+since any string containing a backslash escape doesn't get marked as HTML.
+Since we don't want to escape things that backslash escapes are normally
+used for, this isn't really a problem for us.
+
+=head2 textblock
+
+For no reason I can comprehend at all, L<Template::Directive>'s C<textblock>
+method calls C<&text> instead of using a method call so we have to override
+this as well.
+
+=head1 AUTHORS
+
+See L<HTML::String> for authors.
+
+=head1 COPYRIGHT AND LICENSE
+
+See L<HTML::String> for the copyright and license.
+
+=cut