documentationify

[scpubgit/HTML-String.git] / lib / HTML / String / TT / Directive.pm

diff --git a/lib/HTML/String/TT/Directive.pm b/lib/HTML/String/TT/Directive.pm
index 770f5fa..c28ae28 100644 (file)
--- 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