README
1NAME
2 String::TT - use TT to interpolate lexical variables
3
4SYNOPSIS
5 use String::TT qw/tt strip/;
6
7 sub foo {
8 my $self = shift;
9 return tt 'my name is [% self.name %]!';
10 }
11
12 sub bar {
13 my @args = @_;
14 return strip tt q{
15 Args: [% args_a.join(",") %]
16 }
17 }
18
19DESCRIPTION
20 String::TT exports a "tt" function, which takes a TT (Template Toolkit)
21 template as its argument. It uses the current lexical scope to resolve
22 variable references. So if you say:
23
24 my $foo = 42;
25 my $bar = 24;
26
27 tt '[% foo %] <-> [% bar %]';
28
29 the result will be "42 <-> 24".
30
31 TT provides a slightly less rich namespace for variables than perl, so
32 we have to do some mapping. Arrays are always translated from @array to
33 "array_a" and hashes are always translated from %hash to "hash_h".
34 Scalars are special and retain their original name, but they also get a
35 "scalar_s" alias. Here's an example:
36
37 my $scalar = 'scalar';
38 my @array = qw/array goes here/;
39 my %hash = ( hashes => 'are fun' );
40
41 tt '[% scalar %] [% scalar_s %] [% array_a %] [% hash_h %]';
42
43 There is one special case, and that's when you have a scalar that is
44 named like an existing array or hash's alias:
45
46 my $foo_a = 'foo_a';
47 my @foo = qw/foo array/;
48
49 tt '[% foo_a %] [% foo_a_s %]'; # foo_a is the array, foo_a_s is the scalar
50
51 In this case, the "foo_a" accessor for the "foo_a" scalar will not be
52 generated. You will have to access it via "foo_a_s". If you delete the
53 array, though, then "foo_a" will refer to the scalar.
54
55 This is a very cornery case that you should never encounter unless you
56 are weird. 99% of the time you will just use the variable name.
57
58EXPORT
59 None by default, but "strip" and "tt" are available.
60
61FUNCTIONS
62 tt $template
63 Treats $template as a Template Toolkit template, populated with
64 variables from the current lexical scope.
65
66 strip $text
67 Removes a leading empty line and common leading spaces on each line. For
68 example,
69
70 strip q{
71 This is a test.
72 This is indented.
73 };
74
75 Will yield the string "This is a test\n This is indented.\n".
76
77 This feature is designed to be used like:
78
79 my $data = strip tt q{
80 This is a [% template %].
81 It is easy to read.
82 };
83
84 Instead of the ugly heredoc equivalent:
85
86 my $data = tt <<'EOTT';
87 This is a [% template %].
88 It looks like crap.
89 EOTT
90
91HACKING
92 If you want to pass args to the TT engine, override the
93 "_build_tt_engine" function:
94
95 local *String::TT::_build_tt_engine = sub { return Template->new( ... ) }
96 tt 'this uses my engine';
97
98VERSION CONTROL
99 This module is hosted in the "jrock.us" git repository. You can view the
100 history in your web browser at:
101
102 <http://git.jrock.us/?p=String-TT.git;a=summary>
103
104 and you can clone the repository by running:
105
106 git clone git://git.jrock.us/String-TT
107
108 Patches welcome.
109
110AUTHOR
111 Jonathan Rockway "jrockway@cpan.org"
112
113COPYRIGHT
114 This module is copyright (c) 2008 Infinity Interactive. You may
115 redistribute it under the same terms as Perl itself.
116
117