1Text::Template::Simple:U:sAePrI(C3o)ntributed Perl DocumTeenxtta:t:iToenmplate::Simple::API(3)
2
6 Text::Template::Simple::API
7
9 version 0.91
10
12 use Text::Template::Simple;
13 my $tts = Text::Template::Simple->new();
14 print $tts->compile( $FILEHANDLE );
15 print $tts->compile('Hello, your perl is at <%= $^X %>');
16 print $tts->compile(
17 'hello.tts', # the template file
18 [ name => 'Burak', location => 'Istanbul' ]
19 );
20 Where "hello.tts" has this content:
22 <% my %p = @_; %>
24 Hello <%= $p{name} %>,
25 I hope it's sunny in <%= $p{location} %>.
26 Local time is <%= scalar localtime time %>
27
29 This is a simple template module. There is no extra template/mini
30 language. Instead, it uses Perl as a template language. Templates can
31 be cached on disk or inside the memory via internal cache manager. It
32 is also possible to use static/dynamic includes, pass parameters to
33 includes and allpt filters on them.
34
36 Text::Template::Simple::API - Simple text template engine API reference
37
39 new
40 Creates a new template object and accepts several parameters.
41 add_args
43 ARRAYref. Can be used to add a global parameter list to the templates.
45 $tts = Text::Template::Simple->new(
47 add_args => [qw(foo bar baz)],
48 );
49 and then you can fetch them inside any template that is compiled with
51 $tts object:
52 <%
54 my $foo = shift;
55 my $bar = shift;
56 my $baz = shift;
57 %>
58 Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>
59 But it'll be logical to combine it with "header" parameter:
61 $tts = Text::Template::Simple->new(
63 header => q~my $foo = shift;my $bar = shift;my $baz = shift;~,
64 add_args => [qw(foo bar baz)],
65 );
66 and then you can use it inside any template that is compiled with $tts
68 object without manually fetching all the time:
69 Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>
71 Can be useful, if you want to define a default object:
73 $tts = Text::Template::Simple->new(
75 header => q~my $self = shift;~,
76 add_args => [$my_default_object],
77 );
78 and then you can use it inside any template that is compiled with $tts
80 object without manually fetching:
81 Foo is <%= $self->{foo} %>. Test: <%= $self->method('test') %>
83 cache
85 Pass this with a true value if you want the cache feature. In-memory
87 cache will be used unless you also pass a "cache_dir" parameter.
88 cache_dir
90 If you want disk-based cache, set this parameter to a valid directory
92 path. You must also set "cache" to a true value.
93 capture_warnings
95 If enabled, the warnings generated by the template will be added to the
97 end of the output. This option is disabled by default.
98 delimiters
100 Must be an array ref containing the two delimiter values: the opening
102 delimiter and the closing delimiter:
103 $tts = Text::Template::Simple->new(
105 delimiters => ['<?perl', '?>'],
106 );
107 Default values are "<%" and "%>".
109 header
111 This is a string containing global elements (global to this particular
113 object) for templates. You can define some generally accessible
114 variables with this:
115 $tts = Text::Template::Simple->new(
117 header => q~ my $foo = "bar"; ~,
118 );
119 and then you can use it (without defining) inside any template that is
121 compiled with $tts object:
122 Foo is <%=$foo%>
124 include_paths
126 An ARRAY reference. If you want to use relative file paths when
128 compiling/including template files, add the paths of the templates with
129 this parameter.
130 iolayer
132 This option does not have any effect under perls older than 5.8.0. Set
134 this to "utf8" (no initial colon) if your I/O is "UTF-8". Not tested
135 with other encodings.
136 monolith
138 Controls the behavior when using includes. If this is enabled, the
140 template and all it's includes will be compiled into a single document.
141 If "monolith" is disabled, then the includes will be compiled
142 individually into separate documents.
143 If you need to pass the main template variables ("my" vars) into
145 dynamic includes, then you need to enable this option. However, if you
146 are using the cache, then the included templates will not be updated
147 automatically.
148 "monolith" is disabled by default.
150 pre_chomp
152 use Text::Template::Simple::Constants qw( :chomp );
154 $pre = CHOMP_NONE; # no chomp
155 $pre = CHOMP_ALL; # remove all whitespace
156 $pre = COLLAPSE_ALL; # replace all ws with a single space
157 $tts = Text::Template::Simple->new(
158 pre_chomp => $pre,
159 );
160 post_chomp
162 use Text::Template::Simple::Constants qw( :chomp );
164 $post = CHOMP_NONE; # no chomp
165 $post = CHOMP_ALL; # remove all whitespace
166 $post = COLLAPSE_ALL; # replace all ws with a single space
167 $tts = Text::Template::Simple->new(
168 post_chomp => $post,
169 );
170 safe
172 Set this to a true value if you want to execute the template code in a
174 safe compartment. Disabled by default and highly experimental. This
175 option can also disable some template features.
176 If you want to enable some unsafe conditions, you have to define
178 "Text::Template::Simple::Compiler::Safe::permit" sub in your controller
179 code and return a list of permitted opcodes inside that sub:
180 sub Text::Template::Simple::Compiler::Safe::permit {
182 my $class = shift;
183 return qw(:default :subprocess); # enable backticks and system
184 }
185 If this is not enough for you, you can define the safe compartment all
187 by yourself by defining
188 "Text::Template::Simple::Compiler::Safe::object":
189 sub Text::Template::Simple::Compiler::Safe::object {
191 require Safe;
192 my $safe = Safe->new('Text::Template::Simple::Dummy');
193 $safe->permit(':browse');
194 return $safe;
195 }
196 ":default", "require" and "caller" are enabled opcodes, unless you
198 define your own. You have to disable "strict" option to disable
199 "require" opcode. Disabling "caller" will also make your
200 "require"/"use" calls die in perl 5.9.5 and later.
201 See Safe and especially Opcode for opcode lists and other details.
203 stack
205 This option enables caller stack tracing for templates. The generated
207 list is sent to "warn". So, it is possible to capture this data with a
208 signal handler. See Text::Template::Simple::Caller for available
209 options.
210 It is also possible to send the output to the template output buffer,
212 if you append ":buffer" to the type of the "stack" option:
213 $tts = Text::Template::Simple->new(
215 stack => 'string:buffer',
216 );
217 "html_comment" is the same as "string" except that it also includes
219 HTML comment markers. "text_table" needs the optional module
220 "Text::Table".
221 This option is also available to all templates as a function named
223 "stack" for individual stack dumping. See Text::Template::Simple::Dummy
224 for more information.
225 strict
227 If has a true value, the template will be compiled under strict.
229 Enabled by default.
230 taint_mode
232 You need to run your template controller with the "-T" flag enabled.
234 Then you can set various taint mode options.
235 use Text::Template::Simple::Constants qw(:taint);
237 my $tmode = TAINT_CHECK_FH_READ;
238 my $restrict = Text::Template::Simple->new( taint_mode => $tmode );
239 With the ":taint" key, you'll get access to these constants (bitwise
241 flags):
242 TAINT_CHECK_NORMAL * Default
244 TAINT_CHECK_WINDOWS Some tests are disabled under Windows OS. Enable them
245 TAINT_CHECK_FH_READ FH must only be readable by the current user
246 To have a more strict taint test:
248 $tmode = TAINT_CHECK_FH_READ | TAINT_CHECK_WINDOWS;
250 However, note that this'll cause failures unless file mode is 600. And
252 it will cause failures on Windows.
253 verbose_errors
255 If enabled, you'll get both the parsed structure and a tidied version
257 of it in the error messages. Disabled by default.
258 warn_ids
260 If enabled, the module will warn you about compile steps using template
262 ids. You must both enable this and the cache. If cache is disabled, no
263 warnings will be generated.
264 compile DATA [, FILL_IN_PARAM, OPTIONS]
266 Compiles the template you have passed and manages template cache, if
267 you've enabled cache feature. Then it returns the compiled template.
268 Accepts three different types of data as the first parameter; a
269 reference to a filehandle ("GLOB"), a string or a file path (path to
270 the template file).
271 First parameter (DATA)
273 The first parameter can take four different values; a filehandle, a
275 string, a file path or explicit type definition via an ARRAY reference.
276 Distinguishing filehandles are easy, since they'll be passed as a
277 reference (but see the bareword issue below). So, the only problem is
278 distinguishing strings and file paths. "compile" first checks if the
279 string length is equal or less than 255 characters and then tests if a
280 file with this name exists. If all these tests fail, the string will be
281 treated as the template text.
282 File paths
284 You can pass a file path as the first parameter:
286 $text = $tts->compile('/my/templates/test.tts');
288 Strings
290 You can pass a string as the first parameter:
292 $text = $tts->compile(q~
294 <%for my $i (0..10) {%>
295 counting <%=$i%>...
296 <%}%>
297 ~);
298 Filehandles
300 "GLOB"s must be passed as a reference. If you are using bareword
302 filehandles, be sure to pass it's reference or it'll be treated as a
303 file path and your code will probably "die":
304 open MYHANDLE, '/path/to/foo.tts' or die "Error: $!";
306 $text = $tts->compile(\*MYHANDLE); # RIGHT.
307 $text = $tts->compile( *MYHANDLE); # WRONG. Recognized as a file path
308 $text = $tts->compile( MYHANDLE); # WRONG. Ditto. Dies under strict
309 or use the standard "IO::File" module:
311 use IO::File;
313 my $fh = IO::File->new;
314 $fh->open('/path/to/foo.tts', 'r') or die "Error: $!";
315 $text = $tts->compile($fh);
316 or you can use lexicals inside "open" if you don't care about
318 compatibility with older perl:
319 open my $fh, '/path/to/foo.tts' or die "Error: $!";
321 $text = $tts->compile($fh);
322 Filehandles will not be closed.
324 Explicit Types
326 Pass an arrayref containing the type and the parameter to disable
328 guessing and forcing the type:
329 $text = $tts->compile( [ FILE => '/path/to/my.tts'] );
331 $text = $tts->compile( [ GLOB => \*MYHANDLE] );
332 $text = $tts->compile( [ STRING => 'I am running under <%= $] %>'] );
333 Type can be one of these: "FILE", "GLOB", "STRING".
335 FILL_IN_PARAM
337 An arrayref. Everything inside this will be accessible from the usual
339 @_ array inside templates.
340 OPTIONS
342 A hashref. Several template specific options can be set with this
344 parameter.
345 id
347 Controls the cache id generation. Can be useful, if you want to pass
349 your own template id. If false or set to "AUTO", internal mechanisms
350 will be used to generate template keys.
351 map_keys
353 This will change the compiler behavior. If you enable this, you can
355 construct templates like this:
356 This is "<%foo%>", that is "<%bar%>" and the other is "<%baz%>"
358 i.e.: only the key names can be used instead of perl constructs. and
360 as you can see, ""<%"" is used instead of ""<%="". "map_keys" also
361 disables usage of perl constructs. Only bare words can be used and you
362 don't have to fetch parameters via @_ inside the template. Here is an
363 example:
364 $text = $tts->compile(
366 q~This is "<%foo%>", that is "<%bar%>"
367 and the other is "<%baz%>"~,
368 [
369 foo => "blah 1",
370 bar => "blah 2",
371 baz => "blah 3",
372 ],
373 {
374 map_keys => 1
375 },
376 );
377 Can be good (and simple) for compiling i18n texts. If you don't use
379 "map_keys", the above code must be written as:
380 $text = $tts->compile(
382 q~<%my(%l) = @_%>This is "<%=$l{foo}%>", that is "<%=$l{bar}%>"
383 and the other is "<%=$l{baz}%>"~,
384 [
385 foo => "blah 1",
386 bar => "blah 2",
387 baz => "blah 3",
388 ],
389 );
390 If "map_keys" is set to 'init', then the uninitialized values will be
392 initialized to an empty string. But beware; "init" may cloak template
393 errors. It'll silence uninitialized warnings, but can also make it
394 harder to detect template errors.
395 If "map_keys" is set to 'check', then the compiler will check for the
397 key's existence and check if it is defined or not.
398 chkmt
400 If you are using file templates (i.e.: not FH or not string) and you
402 set this to a true value, modification time of templates will be
403 checked and compared for template change.
404 cache
406 Returns the Text::Template::Simple::Cache object.
407 io
409 Returns the Text::Template::Simple::IO object.
410 connector
412 Returns the class name of the supplied connector.
413 class_id
415 Returns a class identifier.
416
418 These are all global (i.e.: not local to any particular object).
419 DEBUG
421 Used to enable/disable debugging. Debug information is generated as
422 warnings:
423 Text::Template::Simple->DEBUG(1); # enable
425 Text::Template::Simple->DEBUG(0); # disable
426 Text::Template::Simple->DEBUG(2); # more verbose
427 "DEBUG" is disabled by default.
429 DIGEST
431 Returns the digester object:
432 $digester = Text::Template::Simple->DIGEST;
434 print $digester->add($data)->hexdigest;
435
437 Cache manager has two working modes. It can use disk files or memory
438 for the storage. Memory based cache is far more faster than disk cache.
439 The template text is first parsed and compiled into an anonymous perl
441 sub source. Then an unique key is generated from your source data (you
442 can by-pass key generation phase if you supply your own id parameter).
443 If in-memory cache is used, the perl source will be compiled into an
445 anonymous sub inside the in-memory cache hash and this compiled version
446 will be used instead of continiously parsing/compiling the same
447 template.
448 If disk cache is used, a template file with the "".tts.cache""
450 extension will be generated on the disk.
451 Using cache is recommended under persistent environments like
453 "mod_perl" and "PerlEx".
454 In-memory cache can use two or three times more space than disk-cache,
456 but it is far more faster than disk cache. Disk cache can also be
457 slower than no-cache for small templates, since there is a little
458 overhead when generating unique keys with the "DIGESTER" and also there
459 will be a disk I/O. There is a modification time check option for disk
460 based templates (see compile).
461
463 Cache keys are generated with one of these modules:
464 Digest::SHA
466 Digest::SHA1
467 Digest::SHA2
468 Digest::SHA::PurePerl
469 Digest::MD5
470 MD5
471 Digest::Perl::MD5
472 SHA algorithm seems to be more reliable for key generation, but md5 is
474 widely available and "Digest::MD5" is in CORE.
475
477 tts [ NEW_ARGS, ] COMPILE_ARGS
478 This function is a wrapper around the Text::Template::Simple object. It
479 creates it's own temporary object behind the scenes and can be used for
480 quick Perl one-liners for example. Using this function other than
481 testing is not recommended.
482 "NEW_ARGS" is optional and must be a hashref containing the parameters
484 to "new". "COMPILE_ARGS" is a list and everything it contains will be
485 passed to the "compile" method.
486 It is possible to import this function to your namespace:
488 use Text::Template::Simple qw( tts );
490 print tts("<%= scalar localtime time %>");
491 print tts( { strict => 1 }, "<%= scalar localtime time %>");
492
494 Taint checking on filehandles have limited tests under Windows. Since
495 file permission is always 0666, g-o read & g-o write tests are disabled
496 under Windows and g-o read taint checking is also disabled by default
497 on all platforms. However, it is possible to force to enable those. See
498 taint_mode for more information.
499 "monolith" option can not be used with interpolated includes. You'll
501 need to use the "SHARE" commad instead to explicitly share variables
502 with includes.
503
505 Text::Template::Simple.
506
508 Burak Gursoy <burak@cpan.org>
509
511 This software is copyright (c) 2004 by Burak Gursoy.
512 This is free software; you can redistribute it and/or modify it under
514 the same terms as the Perl 5 programming language system itself.
515perl v5.36.0 2023-01-20 Text::Template::Simple::API(3)