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

NAME

6       Text::Template::Simple::API
7

VERSION

9       version 0.91
10

SYNOPSIS

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
21       Where "hello.tts" has this content:
22
23          <% my %p = @_; %>
24          Hello <%= $p{name} %>,
25          I hope it's sunny in <%= $p{location} %>.
26          Local time is <%= scalar localtime time %>
27

DESCRIPTION

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

NAME

36       Text::Template::Simple::API - Simple text template engine API reference
37

METHODS

39   new
40       Creates a new template object and accepts several parameters.
41
42       add_args
43
44       ARRAYref. Can be used to add a global parameter list to the templates.
45
46          $tts = Text::Template::Simple->new(
47             add_args => [qw(foo bar baz)],
48          );
49
50       and then you can fetch them inside any template that is compiled with
51       $tts object:
52
53          <%
54             my $foo = shift;
55             my $bar = shift;
56             my $baz = shift;
57          %>
58          Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>
59
60       But it'll be logical to combine it with "header" parameter:
61
62          $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
67       and then you can use it inside any template that is compiled with $tts
68       object without manually fetching all the time:
69
70          Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>
71
72       Can be useful, if you want to define a default object:
73
74          $tts = Text::Template::Simple->new(
75             header   => q~my $self = shift;~,
76             add_args => [$my_default_object],
77          );
78
79       and then you can use it inside any template that is compiled with $tts
80       object without manually fetching:
81
82          Foo is <%= $self->{foo} %>. Test: <%= $self->method('test') %>
83
84       cache
85
86       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
89       cache_dir
90
91       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
94       capture_warnings
95
96       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
99       delimiters
100
101       Must be an array ref containing the two delimiter values: the opening
102       delimiter and the closing delimiter:
103
104          $tts = Text::Template::Simple->new(
105             delimiters => ['<?perl', '?>'],
106          );
107
108       Default values are "<%" and "%>".
109
110       header
111
112       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
116          $tts = Text::Template::Simple->new(
117             header => q~ my $foo = "bar"; ~,
118          );
119
120       and then you can use it (without defining) inside any template that is
121       compiled with $tts object:
122
123          Foo is <%=$foo%>
124
125       include_paths
126
127       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
131       iolayer
132
133       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
137       monolith
138
139       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
144       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
149       "monolith" is disabled by default.
150
151       pre_chomp
152
153          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
161       post_chomp
162
163          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
171       safe
172
173       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
177       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
181          sub Text::Template::Simple::Compiler::Safe::permit {
182             my $class = shift;
183             return qw(:default :subprocess); # enable backticks and system
184          }
185
186       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
190          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
197       ":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
202       See Safe and especially Opcode for opcode lists and other details.
203
204       stack
205
206       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
211       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
214          $tts = Text::Template::Simple->new(
215             stack => 'string:buffer',
216          );
217
218       "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
222       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
226       strict
227
228       If has a true value, the template will be compiled under strict.
229       Enabled by default.
230
231       taint_mode
232
233       You need to run your template controller with the "-T" flag enabled.
234       Then you can set various taint mode options.
235
236          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
240       With the ":taint" key, you'll get access to these constants (bitwise
241       flags):
242
243          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
247       To have a more strict taint test:
248
249          $tmode = TAINT_CHECK_FH_READ | TAINT_CHECK_WINDOWS;
250
251       However, note that this'll cause failures unless file mode is 600. And
252       it will cause failures on Windows.
253
254       verbose_errors
255
256       If enabled, you'll get both the parsed structure and a tidied version
257       of it in the error messages. Disabled by default.
258
259       warn_ids
260
261       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
265   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
272       First parameter (DATA)
273
274       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
283       File paths
284
285       You can pass a file path as the first parameter:
286
287          $text = $tts->compile('/my/templates/test.tts');
288
289       Strings
290
291       You can pass a string as the first parameter:
292
293          $text = $tts->compile(q~
294          <%for my $i (0..10) {%>
295             counting <%=$i%>...
296          <%}%>
297          ~);
298
299       Filehandles
300
301       "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
305          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
310       or use the standard "IO::File" module:
311
312          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
317       or you can use lexicals inside "open" if you don't care about
318       compatibility with older perl:
319
320          open my $fh, '/path/to/foo.tts' or die "Error: $!";
321          $text = $tts->compile($fh);
322
323       Filehandles will not be closed.
324
325       Explicit Types
326
327       Pass an arrayref containing the type and the parameter to disable
328       guessing and forcing the type:
329
330          $text = $tts->compile( [ FILE   => '/path/to/my.tts'] );
331          $text = $tts->compile( [ GLOB   => \*MYHANDLE] );
332          $text = $tts->compile( [ STRING => 'I am running under <%= $] %>'] );
333
334       Type can be one of these: "FILE", "GLOB", "STRING".
335
336       FILL_IN_PARAM
337
338       An arrayref. Everything inside this will be accessible from the usual
339       @_ array inside templates.
340
341       OPTIONS
342
343       A hashref. Several template specific options can be set with this
344       parameter.
345
346       id
347
348       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
352       map_keys
353
354       This will change the compiler behavior. If you enable this, you can
355       construct templates like this:
356
357          This is "<%foo%>", that is "<%bar%>" and the other is "<%baz%>"
358
359       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
365          $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
378       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
381          $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
391       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
396       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
399       chkmt
400
401       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
405   cache
406       Returns the Text::Template::Simple::Cache object.
407
408   io
409       Returns the Text::Template::Simple::IO object.
410
411   connector
412       Returns the class name of the supplied connector.
413
414   class_id
415       Returns a class identifier.
416

CLASS METHODS

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

CACHE MANAGER

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
440       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
444       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
449       If disk cache is used, a template file with the "".tts.cache""
450       extension will be generated on the disk.
451
452       Using cache is recommended under persistent environments like
453       "mod_perl" and "PerlEx".
454
455       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

DIGESTER

463       Cache keys are generated with one of these modules:
464
465          Digest::SHA
466          Digest::SHA1
467          Digest::SHA2
468          Digest::SHA::PurePerl
469          Digest::MD5
470          MD5
471          Digest::Perl::MD5
472
473       SHA algorithm seems to be more reliable for key generation, but md5 is
474       widely available and "Digest::MD5" is in CORE.
475

FUNCTIONS

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
483       "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
487       It is possible to import this function to your namespace:
488
489          use Text::Template::Simple qw( tts );
490          print tts("<%= scalar localtime time %>");
491          print tts( { strict => 1 }, "<%= scalar localtime time %>");
492

CAVEATS

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
500       "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

SEE ALSO

505       Text::Template::Simple.
506

AUTHOR

508       Burak Gursoy <burak@cpan.org>
509
511       This software is copyright (c) 2004 by Burak Gursoy.
512
513       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.
515
516
517
518perl v5.36.0                      2023-01-20    Text::Template::Simple::API(3)
Impressum