NAME
    String::TT - use TT to interpolate lexical variables

SYNOPSIS
      use String::TT qw/tt strip/;

      sub foo {
         my $self = shift;
         return tt 'my name is [% self.name %]!';
      }

      sub bar {
         my @args = @_;
         return strip tt q{
            Args: [% args_a.join(",") %]
         }
      }

DESCRIPTION
    String::TT exports a "tt" function, which takes a TT (Template Toolkit)
    template as its argument. It uses the current lexical scope to resolve
    variable references. So if you say:

      my $foo = 42;
      my $bar = 24;

      tt '[% foo %] <-> [% bar %]';

    the result will be "42 <-> 24".

    TT provides a slightly less rich namespace for variables than perl, so
    we have to do some mapping. Arrays are always translated from @array to
    "array_a" and hashes are always translated from %hash to "hash_h".
    Scalars are special and retain their original name, but they also get a
    "scalar_s" alias. Here's an example:

      my $scalar = 'scalar';
      my @array  = qw/array goes here/;
      my %hash   = ( hashes => 'are fun' );

      tt '[% scalar %] [% scalar_s %] [% array_a %] [% hash_h %]';

    There is one special case, and that's when you have a scalar that is
    named like an existing array or hash's alias:

      my $foo_a = 'foo_a';
      my @foo   = qw/foo array/;

      tt '[% foo_a %] [% foo_a_s %]'; # foo_a is the array, foo_a_s is the scalar

    In this case, the "foo_a" accessor for the "foo_a" scalar will not be
    generated. You will have to access it via "foo_a_s". If you delete the
    array, though, then "foo_a" will refer to the scalar.

    This is a very cornery case that you should never encounter unless you
    are weird. 99% of the time you will just use the variable name.

EXPORT
    None by default, but "strip" and "tt" are available.

FUNCTIONS
  tt $template
    Treats $template as a Template Toolkit template, populated with
    variables from the current lexical scope.

  strip $text
    Removes a leading empty line and common leading spaces on each line. For
    example,

      strip q{
        This is a test.
         This is indented.
      };

    Will yield the string "This is a test\n This is indented.\n".

    This feature is designed to be used like:

      my $data = strip tt q{
          This is a [% template %].
          It is easy to read.
      };

    Instead of the ugly heredoc equivalent:

      my $data = tt <<'EOTT';
    This is a [% template %].
    It looks like crap.
    EOTT

HACKING
    If you want to pass args to the TT engine, override the
    "_build_tt_engine" function:

      local *String::TT::_build_tt_engine = sub { return Template->new( ... ) }
      tt 'this uses my engine';

VERSION CONTROL
    This module is hosted in the "jrock.us" git repository. You can view the
    history in your web browser at:

    <http://git.jrock.us/?p=String-TT.git;a=summary>

    and you can clone the repository by running:

      git clone git://git.jrock.us/String-TT

    Patches welcome.

AUTHOR
    Jonathan Rockway "jrockway@cpan.org"

COPYRIGHT
    This module is copyright (c) 2008 Infinity Interactive. You may
    redistribute it under the same terms as Perl itself.

