String::TT(3pm)

💖 String::TT — bestie, it's a Perl module 💖

okay so this is the manual page for String::TT, which lives in the User Contributed Perl Documentation section of the perl man pages. yes she's a 3pm girlie. we love her. 💅

---

✨ NAME ✨

String::TT — use TT to interpolate lexical variables. that's it, that's the whole vibe. TT = Template Toolkit, lexical variables = your my variables, and this module introduces them to each other like a very good friend at a party 🫶

---

🌸 SYNOPSIS 🌸

here's how you actually use her:

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(",") %]
   }
}

see how tt just... knows about $self and @args?? no passing hashes around, no { self => $self }, nothing. she's literally reading your lexical scope. iconic behavior. 👑

---

💜 DESCRIPTION 💜

String::TT exports a tt function, and what it does is take a TT (Template Toolkit) template as its argument. then it uses the current lexical scope to resolve variable references. so, like, if you say:

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

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

the result will be 42 <-> 24. no cap. ✨

---

now here's the tea ☕ — TT gives you a slightly less rich namespace for variables than perl does, so some mapping has to happen. it's giving translation layer. it's giving adapters. here's the rules:

• Arrays are always translated from @array to array_a 🦋
• Hashes are always translated from %hash to hash_h 🎀
• Scalars are special and keep their original name, but they also get a scalar_s alias ✨

example time:

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

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

🚨 the one special case 🚨

there is one special case, and it's when you have a scalar that is named like an existing array's 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. so you'll have to access it via foo_a_s instead. the array won. the array ate. 💀

but if you delete the array, though? then foo_a will refer to the scalar. so like, the scalar was just waiting its turn. patient queen.

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. fr fr. 🙈

---

🌈 EXPORT 🌈

None by default, but strip and tt are available. so if you want them, ask nicely (with qw/tt strip/). 🫶

---

🎀 FUNCTIONS 🎀

tt $template

Treats $template as a Template Toolkit template, populated with variables from the current lexical scope. that's her whole job and she does it flawlessly. ⭐

strip $text

Removes a leading empty line and common leading spaces on each line. so it un-uglies your indented heredoc-adjacent strings. 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

see?? strip said "not on my watch." she said "you will have nice indentation in your source AND nice output." she understood the assignment. 🔥

---

💅 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';

yes bestie, local on a glob, yes it's a little feral, no we're not apologizing. 😌

---

🦋 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. 👑 (they literally said that. come contribute.)

---

🌸 AUTHOR 🌸

Jonathan Rockway jrockway@cpan.org — the legend, the moment, the main character 💖

---

✨ COPYRIGHT ✨

this module is copyright (c) 2008 Infinity Interactive. you may redistribute it under the same terms as Perl itself. so like, go forth, be free, respect the license bestie 🫶

---

and that's the whole page!! 😭🫶 this was written against perl v5.34.0 and dated 2022-06-17, which is when this particular String::TT(3pm) page got rendered. mwah. go interpolate something. 💜