Text::Template::Simple::API(3pm)

1Text::Template::Simple:U:sAePrI(C3o)ntributed Perl DocumTeenxtta:t:iToenmplate::Simple::API(3)
2
3
4

NAME

6       Text::Template::Simple::API - Simple text template engine API reference
7

SYNOPSIS

9          use Text::Template::Simple;
10          my $tts = Text::Template::Simple->new();
11          print $tts->compile( $FILEHANDLE );
12          print $tts->compile('Hello, your perl is at <%= $^X %>');
13          print $tts->compile(
14                   'hello.tts', # the template file
15                   [ name => 'Burak', location => 'Istanbul' ]
16                );
17
18       Where "hello.tts" has this content:
19
20          <% my %p = @_; %>
21          Hello <%= $p{name} %>,
22          I hope it's sunny in <%= $p{location} %>.
23          Local time is <%= scalar localtime time %>
24

DESCRIPTION

26       This is a simple template module. There is no extra template/mini
27       language. Instead, it uses Perl as a template language. Templates can
28       be cached on disk or inside the memory via internal cache manager. It
29       is also possible to use static/dynamic includes, pass parameters to
30       includes and allpt filters on them.
31

METHODS

33   new
34       Creates a new template object and accepts several parameters.
35
36       add_args
37
38       ARRAYref. Can be used to add a global parameter list to the templates.
39
40          $tts = Text::Template::Simple->new(
41             add_args => [qw(foo bar baz)],
42          );
43
44       and then you can fetch them inside any template that is compiled with
45       $tts object:
46
47          <%
48             my $foo = shift;
49             my $bar = shift;
50             my $baz = shift;
51          %>
52          Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>
53
54       But it'll be logical to combine it with "header" parameter:
55
56          $tts = Text::Template::Simple->new(
57             header   => q~my $foo = shift;my $bar = shift;my $baz = shift;~,
58             add_args => [qw(foo bar baz)],
59          );
60
61       and then you can use it inside any template that is compiled with $tts
62       object without manually fetching all the time:
63
64          Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>
65
66       Can be useful, if you want to define a default object:
67
68          $tts = Text::Template::Simple->new(
69             header   => q~my $self = shift;~,
70             add_args => [$my_default_object],
71          );
72
73       and then you can use it inside any template that is compiled with $tts
74       object without manually fetching:
75
76          Foo is <%= $self->{foo} %>. Test: <%= $self->method('test') %>
77
78       cache
79
80       Pass this with a true value if you want the cache feature.  In-memory
81       cache will be used unless you also pass a "cache_dir" parameter.
82
83       cache_dir
84
85       If you want disk-based cache, set this parameter to a valid directory
86       path. You must also set "cache" to a true value.
87
88       capture_warnings
89
90       If enabled, the warnings generated by the template will be added to the
91       end of the output. This option is disabled by default.
92
93       delimiters
94
95       Must be an array ref containing the two delimiter values: the opening
96       delimiter and the closing delimiter:
97
98          $tts = Text::Template::Simple->new(
99             delimiters => ['<?perl', '?>'],
100          );
101
102       Default values are "<%" and "%>".
103
104       header
105
106       This is a string containing global elements (global to this particular
107       object) for templates. You can define some generally accessible
108       variables with this:
109
110          $tts = Text::Template::Simple->new(
111             header => q~ my $foo = "bar"; ~,
112          );
113
114       and then you can use it (without defining) inside any template that is
115       compiled with $tts object:
116
117          Foo is <%=$foo%>
118
119       include_paths
120
121       An ARRAY reference. If you want to use relative file paths when
122       compiling/including template files, add the paths of the templates with
123       this parameter.
124
125       iolayer
126
127       This option does not have any effect under perls older than 5.8.0.  Set
128       this to "utf8" (no initial colon) if your I/O is "UTF-8".  Not tested
129       with other encodings.
130
131       monolith
132
133       Controls the behavior when using includes. If this is enabled, the
134       template and all it's includes will be compiled into a single document.
135       If "monolith" is disabled, then the includes will be compiled
136       individually into separate documents.
137
138       If you need to pass the main template variables ("my" vars) into
139       dynamic includes, then you need to enable this option. However, if you
140       are using the cache, then the included templates will not be updated
141       automatically.
142
143       "monolith" is disabled by default.
144
145       pre_chomp
146
147          use Text::Template::Simple::Constants qw( :chomp );
148          $pre = CHOMP_NONE; # no chomp
149          $pre = CHOMP_ALL;  # remove all whitespace
150          $pre = COLLAPSE_ALL; # replace all ws with a single space
151          $tts = Text::Template::Simple->new(
152             pre_chomp => $pre,
153          );
154
155       post_chomp
156
157          use Text::Template::Simple::Constants qw( :chomp );
158          $post = CHOMP_NONE; # no chomp
159          $post = CHOMP_ALL;  # remove all whitespace
160          $post = COLLAPSE_ALL; # replace all ws with a single space
161          $tts = Text::Template::Simple->new(
162             post_chomp => $post,
163          );
164
165       safe
166
167       Set this to a true value if you want to execute the template code in a
168       safe compartment. Disabled by default and highly experimental. This
169       option can also disable some template features.
170
171       If you want to enable some unsafe conditions, you have to define
172       "Text::Template::Simple::Compiler::Safe::permit" sub in your controller
173       code and return a list of permitted opcodes inside that sub:
174
175          sub Text::Template::Simple::Compiler::Safe::permit {
176             my $class = shift;
177             return qw(:default :subprocess); # enable backticks and system
178          }
179
180       If this is not enough for you, you can define the safe compartment all
181       by yourself by defining
182       "Text::Template::Simple::Compiler::Safe::object":
183
184          sub Text::Template::Simple::Compiler::Safe::object {
185             require Safe;
186             my $safe = Safe->new('Text::Template::Simple::Dummy');
187             $safe->permit(':browse');
188             return $safe;
189          }
190
191       ":default", "require" and "caller" are enabled opcodes, unless you
192       define your own. You have to disable "strict" option to disable
193       "require" opcode. Disabling "caller" will also make your
194       "require"/"use" calls die in perl 5.9.5 and later.
195
196       See Safe and especially Opcode for opcode lists and other details.
197
198       stack
199
200       This option enables caller stack tracing for templates. The generated
201       list is sent to "warn". So, it is possible to capture this data with a
202       signal handler. See Text::Template::Simple::Caller for available
203       options.
204
205       It is also possible to send the output to the template output buffer,
206       if you append ":buffer" to the type of the "stack" option:
207
208          $tts = Text::Template::Simple->new(
209             stack => 'string:buffer',
210          );
211
212       "html_comment" is the same as "string" except that it also includes
213       HTML comment markers. "text_table" needs the optional module
214       "Text::Table".
215
216       This option is also available to all templates as a function named
217       "stack" for individual stack dumping. See Text::Template::Simple::Dummy
218       for more information.
219
220       strict
221
222       If has a true value, the template will be compiled under strict.
223       Enabled by default.
224
225       taint_mode
226
227       You need to run your template controller with the "-T" flag enabled.
228       Then you can set various taint mode options.
229
230          use Text::Template::Simple::Constants qw(:taint);
231          my $tmode = TAINT_CHECK_FH_READ;
232          my $restrict = Text::Template::Simple->new( taint_mode => $tmode );
233
234       With the ":taint" key, you'll get access to these constants (bitwise
235       flags):
236
237          TAINT_CHECK_NORMAL    * Default
238          TAINT_CHECK_WINDOWS   Some tests are disabled under Windows OS. Enable them
239          TAINT_CHECK_FH_READ   FH must only be readable by the current user
240
241       To have a more strict taint test:
242
243          $tmode = TAINT_CHECK_FH_READ | TAINT_CHECK_WINDOWS;
244
245       However, note that this'll cause failures unless file mode is 600. And
246       it will cause failures on Windows.
247
248       verbose_errors
249
250       If enabled, you'll get both the parsed structure and a tidied version
251       of it in the error messages. Disabled by default.
252
253       warn_ids
254
255       If enabled, the module will warn you about compile steps using template
256       ids. You must both enable this and the cache. If cache is disabled, no
257       warnings will be generated.
258
259   compile DATA [, FILL_IN_PARAM, OPTIONS]
260       Compiles the template you have passed and manages template cache, if
261       you've enabled cache feature. Then it returns the compiled template.
262       Accepts three different types of data as the first parameter; a
263       reference to a filehandle ("GLOB"), a string or a file path (path to
264       the template file).
265
266       First parameter (DATA)
267
268       The first parameter can take four different values; a filehandle, a
269       string, a file path or explicit type definition via an ARRAY reference.
270       Distinguishing filehandles are easy, since they'll be passed as a
271       reference (but see the bareword issue below).  So, the only problem is
272       distinguishing strings and file paths.  "compile" first checks if the
273       string length is equal or less than 255 characters and then tests if a
274       file with this name exists. If all these tests fail, the string will be
275       treated as the template text.
276
277       File paths
278
279       You can pass a file path as the first parameter:
280
281          $text = $tts->compile('/my/templates/test.tts');
282
283       Strings
284
285       You can pass a string as the first parameter:
286
287          $text = $tts->compile(q~
288          <%for my $i (0..10) {%>
289             counting <%=$i%>...
290          <%}%>
291          ~);
292
293       Filehandles
294
295       "GLOB"s must be passed as a reference. If you are using bareword
296       filehandles, be sure to pass it's reference or it'll be treated as a
297       file path and your code will probably "die":
298
299          open MYHANDLE, '/path/to/foo.tts' or die "Error: $!";
300          $text = $tts->compile(\*MYHANDLE); # RIGHT.
301          $text = $tts->compile( *MYHANDLE); # WRONG. Recognized as a file path
302          $text = $tts->compile(  MYHANDLE); # WRONG. Ditto. Dies under strict
303
304       or use the standard "IO::File" module:
305
306          use IO::File;
307          my $fh = IO::File->new;
308          $fh->open('/path/to/foo.tts', 'r') or die "Error: $!";
309          $text = $tts->compile($fh);
310
311       or you can use lexicals inside "open" if you don't care about
312       compatibility with older perl:
313
314          open my $fh, '/path/to/foo.tts' or die "Error: $!";
315          $text = $tts->compile($fh);
316
317       Filehandles will not be closed.
318
319       Explicit Types
320
321       Pass an arrayref containing the type and the parameter to disable
322       guessing and forcing the type:
323
324          $text = $tts->compile( [ FILE   => '/path/to/my.tts'] );
325          $text = $tts->compile( [ GLOB   => \*MYHANDLE] );
326          $text = $tts->compile( [ STRING => 'I am running under <%= $] %>'] );
327
328       Type can be one of these: "FILE", "GLOB", "STRING".
329
330       FILL_IN_PARAM
331
332       An arrayref. Everything inside this will be accessible from the usual
333       @_ array inside templates.
334
335       OPTIONS
336
337       A hashref. Several template specific options can be set with this
338       parameter.
339
340       id
341
342       Controls the cache id generation. Can be useful, if you want to pass
343       your own template id. If false or set to "AUTO", internal mechanisms
344       will be used to generate template keys.
345
346       map_keys
347
348       This will change the compiler behavior. If you enable this, you can
349       construct templates like this:
350
351          This is "<%foo%>", that is "<%bar%>" and the other is "<%baz%>"
352
353       i.e.: only  the key names can be used instead of perl constructs.  and
354       as you can see, ""<%"" is used instead of ""<%="".  "map_keys" also
355       disables usage of perl constructs. Only bare words can be used and you
356       don't have to fetch parameters via @_ inside the template. Here is an
357       example:
358
359          $text = $tts->compile(
360                   q~This is "<%foo%>", that is "<%bar%>"
361                     and the other is "<%baz%>"~,
362                   [
363                      foo => "blah 1",
364                      bar => "blah 2",
365                      baz => "blah 3",
366                   ],
367                   {
368                      map_keys => 1
369                   },
370          );
371
372       Can be good (and simple) for compiling i18n texts. If you don't use
373       "map_keys", the above code must be written as:
374
375          $text = $tts->compile(
376                   q~<%my(%l) = @_%>This is "<%=$l{foo}%>", that is "<%=$l{bar}%>"
377                     and the other is "<%=$l{baz}%>"~,
378                   [
379                      foo => "blah 1",
380                      bar => "blah 2",
381                      baz => "blah 3",
382                   ],
383          );
384
385       If "map_keys" is set to 'init', then the uninitialized values will be
386       initialized to an empty string. But beware; "init" may cloak template
387       errors. It'll silence uninitialized warnings, but can also make it
388       harder to detect template errors.
389
390       If "map_keys" is set to 'check', then the compiler will check for the
391       key's existence and check if it is defined or not.
392
393       chkmt
394
395       If you are using file templates (i.e.: not FH or not string) and you
396       set this to a true value, modification time of templates will be
397       checked and compared for template change.
398
399   cache
400       Returns the Text::Template::Simple::Cache object.
401
402   io
403       Returns the Text::Template::Simple::IO object.
404
405   connector
406       Returns the class name of the supplied connector.
407
408   class_id
409       Returns a class identifier.
410

CLASS METHODS

412       These are all global (i.e.: not local to any particular object).
413
414   DEBUG
415       Used to enable/disable debugging. Debug information is generated as
416       warnings:
417
418          Text::Template::Simple->DEBUG(1); # enable
419          Text::Template::Simple->DEBUG(0); # disable
420          Text::Template::Simple->DEBUG(2); # more verbose
421
422       "DEBUG" is disabled by default.
423
424   DIGEST
425       Returns the digester object:
426
427          $digester = Text::Template::Simple->DIGEST;
428          print $digester->add($data)->hexdigest;
429

CACHE MANAGER

431       Cache manager has two working modes. It can use disk files or memory
432       for the storage. Memory based cache is far more faster than disk cache.
433
434       The template text is first parsed and compiled into an anonymous perl
435       sub source. Then an unique key is generated from your source data (you
436       can by-pass key generation phase if you supply your own id parameter).
437
438       If in-memory cache is used, the perl source will be compiled into an
439       anonymous sub inside the in-memory cache hash and this compiled version
440       will be used instead of continiously parsing/compiling the same
441       template.
442
443       If disk cache is used, a template file with the "".tts.cache""
444       extension will be generated on the disk.
445
446       Using cache is recommended under persistent environments like
447       "mod_perl" and "PerlEx".
448
449       In-memory cache can use two or three times more space than disk-cache,
450       but it is far more faster than disk cache. Disk cache can also be
451       slower than no-cache for small templates, since there is a little
452       overhead when generating unique keys with the "DIGESTER" and also there
453       will be a disk I/O. There is a modification time check option for disk
454       based templates (see compile).
455

DIGESTER

457       Cache keys are generated with one of these modules:
458
459          Digest::SHA
460          Digest::SHA1
461          Digest::SHA2
462          Digest::SHA::PurePerl
463          Digest::MD5
464          MD5
465          Digest::Perl::MD5
466
467       SHA algorithm seems to be more reliable for key generation, but md5 is
468       widely available and "Digest::MD5" is in CORE.
469

FUNCTIONS

471   tts [ NEW_ARGS, ] COMPILE_ARGS
472       This function is a wrapper around the Text::Template::Simple object. It
473       creates it's own temporary object behind the scenes and can be used for
474       quick Perl one-liners for example. Using this function other than
475       testing is not recommended.
476
477       "NEW_ARGS" is optional and must be a hashref containing the parameters
478       to "new". "COMPILE_ARGS" is a list and everything it contains will be
479       passed to the "compile" method.
480
481       It is possible to import this function to your namespace:
482
483          use Text::Template::Simple qw( tts );
484          print tts("<%= scalar localtime time %>");
485          print tts( { strict => 1 }, "<%= scalar localtime time %>");
486

CAVEATS

488       Taint checking on filehandles have limited tests under Windows. Since
489       file permission is always 0666, g-o read & g-o write tests are disabled
490       under Windows and g-o read taint checking is also disabled by default
491       on all platforms. However, it is possible to force to enable those. See
492       taint_mode for more information.
493
494       "monolith" option can not be used with interpolated includes. You'll
495       need to use the "SHARE" commad instead to explicitly share variables
496       with includes.
497