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.

• Igor Vlasenko

• perl-String-TT