1Text::Template::Simple(U3s)er Contributed Perl DocumentatTieoxnt::Template::Simple(3)
2
3
4

NAME

6       Text::Template::Simple
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 the template language. Templates can
31       be cached on disk or inside the memory via the internal cache manager.
32       It is also possible to use static/dynamic includes, pass parameters to
33       includes and apply filters on them.  Also see
34       Text::Template::Simple::API for the full "API" reference.
35

NAME

37       Text::Template::Simple - Simple text template engine
38

SYNTAX

40       Template syntax is very simple. There are few kinds of delimiters:
41
42       •   "<% %>" Code Blocks
43
44       •   "<%= %>" Self-printing Blocks
45
46       •   "<%! %>" Escaped Delimiters
47
48       •   "<%+ %>" Static Include Directives
49
50       •   "<%* %>" Dynamic include directives
51
52       •   "<%# %>" Comment Directives
53
54       •   "<%| %>" Blocks with commands
55
56       A simple example:
57
58          <% foreach my $x (@foo) { %>
59             Element is <%= $x %>
60          <% } %>
61
62       Do not directly use print() statements, since they'll break the
63       template compilation. Use the self printing "<%= %>" blocks.
64
65       It is also possible to alter the delimiters:
66
67          $tts = Text::Template::Simple->new(
68             delimiters => [qw/<?perl ?>/],
69          );
70
71       then you can use them inside templates:
72
73          <?perl
74             my @foo = qw(bar baz);
75             foreach my $x (@foo) {
76          ?>
77          Element is <?perl= $x ?>
78          <?perl } ?>
79
80       If you need to remove a code temporarily without deleting, or need to
81       add comments:
82
83          <%#
84             This
85             whole
86             block
87             will
88             be
89             ignored
90          %>
91
92       If you put a space before the pound sign, the block will be a code
93       block:
94
95          <%
96             # this is normal code not a comment directive
97             my $foo = 42;
98          %>
99
100       If you want to include a text or HTML file, you can use the static
101       include directive:
102
103          <%+ my_other.html %>
104          <%+ my_other.txt  %>
105
106       Included files won't be parsed and included statically. To enable
107       parsing for the included files, use the dynamic includes:
108
109          <%* my_other.html %>
110          <%* my_other.txt  %>
111
112       Interpolation is also supported with both kinds of includes, so the
113       following is valid code:
114
115          <%+ "/path/to/" . $txt    %>
116          <%* "/path/to/" . $myfile %>
117
118   Chomping
119       Chomping is the removal of white space before and after your
120       directives. This can be useful if you're generating plain text (instead
121       of HTML which will ignore spaces most of the time). You can either
122       remove all space or replace multiple white space with a single space
123       (collapse). Chomping can be enabled per directive or globally via
124       options to the constructor.  See "pre_chomp" in
125       Text::Template::Simple::API and "post_chomp" in
126       Text::Template::Simple::API options to "new" in
127       Text::Template::Simple::API to globally enable chomping.
128
129       Chomping is enabled with second level commands for all directives. Here
130       is a list of commands:
131
132          -   Chomp
133          ~   Collapse
134          ^   No chomp (override global)
135
136       All directives can be chomped. Here are some examples:
137
138       Chomp:
139
140          raw content
141          <%- my $foo = 42; -%>
142          raw content
143          <%=- $foo -%>
144          raw content
145          <%*- /mt/dynamic.tts  -%>
146          raw content
147
148       Collapse:
149
150          raw content
151          <%~ my $foo = 42; ~%>
152          raw content
153          <%=~ $foo ~%>
154          raw content
155          <%*~ /mt/dynamic.tts  ~%>
156          raw content
157
158       No chomp:
159
160          raw content
161          <%^ my $foo = 42; ^%>
162          raw content
163          <%=^ $foo ^%>
164          raw content
165          <%*^ /mt/dynamic.tts  ^%>
166          raw content
167
168       It is also possible to mix the chomping types:
169
170          raw content
171          <%- my $foo = 42; ^%>
172          raw content
173          <%=^ $foo ~%>
174          raw content
175          <%*^ /mt/dynamic.tts  -%>
176          raw content
177
178       For example this template:
179
180          Foo
181          <%- $prehistoric = $] < 5.008 -%>
182          Bar
183
184       Will become:
185
186          FooBar
187
188       And this one:
189
190          Foo
191          <%~ $prehistoric = $] < 5.008 -%>
192          Bar
193
194       Will become:
195
196          Foo Bar
197
198       Chomping is inspired by Template Toolkit (mostly the same
199       functionality, although "TT" seems to miss collapse/no-chomp per
200       directive option).
201
202   Accessing Template Names
203       You can use $0 to get the template path/name inside the template:
204
205          I am <%= $0 %>
206
207   Escaping Delimiters
208       If you have to build templates like this:
209
210          Test: <%abc>
211
212       or this:
213
214          Test: <%abc%>
215
216       This will result with a template compilation error. You have to use the
217       delimiter escape command "!":
218
219          Test: <%!abc>
220          Test: <%!abc%>
221
222       Those will be compiled as:
223
224          Test: <%abc>
225          Test: <%abc%>
226
227       Alternatively, you can change the default delimiters to solve this
228       issue.  See the "delimiters" in Text::Template::Simple::API option for
229       "new" in Text::Template::Simple::API for more information on how to do
230       this.
231
232   Template Parameters
233       You can fetch parameters (passed to compile) in the usual "perl" way:
234
235          <%
236             my $foo = shift;
237             my %bar = @_;
238          %>
239          Baz is <%= $bar{baz} %>
240
241   INCLUDE COMMANDS
242       Include commands are separated by pipes in an include directive.
243       Currently supported parameters are:
244
245       "PARAM"
246       FILTER
247       SHARE
248
249          <%+ /path/to/static.tts  | FILTER: MyFilter %>
250          <%* /path/to/dynamic.tts | FILTER: MyFilter | PARAM: test => 123 %>
251
252       "PARAM" defines the parameter list to pass to the included file.
253       "FILTER" defines the list of filters to apply to the output of the
254       include.  "SHARE" used to list the variables to share with the included
255       template when the monolith option is disabled.
256
257       INCLUDE FILTERS
258
259       Use the include command "FILTER:" (notice the colon in the command):
260
261          <%+ /path/to/static.tts  | FILTER: First, Second        %>
262          <%* /path/to/dynamic.tts | FILTER: Third, Fourth, Fifth %>
263
264       IMPLEMENTING INCLUDE FILTERS
265
266       Define the filter inside "Text::Template::Simple::Dummy" with a
267       "filter_" prefix:
268
269          package Text::Template::Simple::Dummy;
270          sub filter_MyFilter {
271             # $tts is the current Text::Template::Simple object
272             # $output_ref is the scalar reference to the output of
273             #    the template.
274             my($tts, $output_ref) = @_;
275             $$output_ref .= "FILTER APPLIED"; # add to output
276             return;
277          }
278
279       INCLUDE PARAMETERS
280
281       Just pass the parameters as described above and fetch them via @_
282       inside the included file.
283
284       SHARED VARIABLES
285
286       "Text::Template::Simple" compiles every template individually with
287       separate scopes. A variable defined in the master template is not
288       accessible from a dynamic include. The exception to this rule is the
289       "monolith" option to "new".  If it is enabled; the master template and
290       any includes it has will be compiled into a single document, thus
291       making every variable defined at the top available to the includes
292       below. But this method has several drawbacks, it disables cache check
293       for the sub files (includes) --you'll need to edit the master template
294       to force a cache reload-- and it can not be used with interpolated
295       includes.  If you use an interpolated include with monolith enabled,
296       you'll get an error.
297
298       If you don't use "monolith" (disabled by default), then you'll need to
299       share the variables somehow to don't repeat yourself. Variable sharing
300       is demonstrated in the below template:
301
302          <%
303             my $foo = 42;
304             my $bar = 23;
305          %>
306          <%* dyna.inc | SHARE: $foo, $bar %>
307
308       And then you can access $foo and $bar inside "dyna.inc". There is one
309       drawback by shared variables: only "SCALARs" can be shared. You can not
310       share anything else. If you want to share an array, use an array
311       reference instead:
312
313          <%
314             my @foo = (1..10);
315             my $fooref = \@foo;
316          %>
317          <%* dyna.inc | SHARE: $fooref %>
318
319   BLOCKS
320       A block consists of a header part and the content.
321
322          <%| HEADER;
323              BODY
324          %>
325
326       "HEADER" includes the commands and terminated with a semicolon. "BODY"
327       is the actual block content.
328
329       BLOCK FILTERS
330
331       WARNING Block filters are considered to be experimental. They may be
332       changed or completely removed in the future.
333
334       Identical to include filters, but works on blocks of text:
335
336          <%| FILTER: HTML, OtherFilter;
337             <p>&FooBar=42</p>
338          %>
339
340       Note that you can not use any variables in these blocks. They are
341       static.
342

METHODS & FUNCTIONS

344   new
345   cache
346   class_id
347   compile
348   connector
349   "io"
350   "tts"
351       See Text::Template::Simple::API for the technical/gory details.
352

EXAMPLES

354          TODO
355

ERROR HANDLING

357       You may need to "eval" your code blocks to trap exceptions. Some
358       recoverable failures are silently ignored, but you can display them as
359       warnings if you enable debugging.
360

BUGS

362       Contact the author if you find any bugs.
363

CAVEATS

365   No mini language
366       There is no mini-language. Only "perl" is used as the template
367       language. So, this may or may not be safe from your point of view. If
368       this is a problem for you, just don't use this module. There are plenty
369       of template modules with mini-languages inside "CPAN".
370
371   Speed
372       There is an initialization cost and this will show itself after the
373       first compilation process. The second and any following compilations
374       will be much faster. Using cache can also improve speed, since this
375       will eliminate the parsing phase. Also, using memory cache will make
376       the program run more faster under persistent environments. But the
377       overall speed really depends on your environment.
378
379       Internal cache manager generates ids for all templates. If you supply
380       your own id parameter, this will improve performance.
381
382   Optional Dependencies
383       Some methods/functionality of the module needs these optional modules:
384
385          Devel::Size
386          Text::Table
387          Perl::Tidy
388

SEE ALSO

390       Text::Template::Simple::API, Apache::SimpleTemplate, Text::Template,
391       Text::ScriptTemplate, Safe, Opcode.
392
393   MONOLITHIC VERSION
394       "Text::Template::Simple" consists of "15+" separate modules. If you are
395       after a single ".pm" file to ease deployment, download the distribution
396       from a "CPAN" mirror near you to get a monolithic
397       "Text::Template::Simple".  It is automatically generated from the
398       separate modules and distributed in the "monolithic_version" directory.
399
400       However, be aware that the monolithic version is not supported.
401

AUTHOR

403       Burak Gursoy <burak@cpan.org>
404
406       This software is copyright (c) 2004 by Burak Gursoy.
407
408       This is free software; you can redistribute it and/or modify it under
409       the same terms as the Perl 5 programming language system itself.
410
411
412
413perl v5.32.1                      2021-01-27         Text::Template::Simple(3)
Impressum