README
1NAME
2
3 Text::NeatTemplate - a fast, middleweight template engine.
4
5SYNOPSIS
6
7 use Text::NeatTemplate;
8
9 my $tobj = Text::NeatTemplate->new();
10
11 $result = $tobj->fill_in(data_hash=>\%data,
12 show_names=>\%names,
13 template=>$text);
14
15DESCRIPTION
16
17 This module provides a simple, middleweight but fast template engine,
18 for when you need speed rather than complex features, yet need more
19 features than simple variable substitution.
20
21 Markup Format
22
23 The markup format is as follows:
24
25 {$varname}
26
27 A variable; will display the value of the variable, or nothing if
28 that value is empty.
29
30 {$varname:format}
31
32 A formatted variable; will apply the formatting directive(s) to the
33 value before displaying it.
34
35 {?varname stuff [$varname] more stuff}
36
37 A conditional. If the value of 'varname' is not empty, this will
38 display "stuff value-of-variable more stuff"; otherwise it displays
39 nothing.
40
41 {?var1 stuff [$var1] thing [$var2]}
42
43 This would use both the values of var1 and var2 if var1 is not empty.
44
45 {?varname stuff [$varname] more stuff!!other stuff}
46
47 A conditional with "else". If the value of 'varname' is not empty,
48 this will display "stuff value-of-variable more stuff"; otherwise it
49 displays "other stuff".
50
51 This version can likewise use multiple variables in its display
52 parts.
53
54 {?var1 stuff [$var1] thing [$var2]!![$var3]}
55
56 {&funcname(arg1,...,argN)}
57
58 Call a function with the given args; the return value of the function
59 will be what is put in its place.
60
61 {&MyPackage::myfunc(stuff,[$var1])}
62
63 This would call the function myfunc in the package MyPackage, with
64 the arguments "stuff", and the value of var1.
65
66 Note, of course, that if you have a more complicated function and are
67 processing much data, this will slow things down.
68
69 Limitations
70
71 To make the parsing simpler (and therefore faster) there are certain
72 restrictions in what this module can do:
73
74 * One cannot escape '{' '}' '[' or ']' characters. However, the
75 substitution is clever enough so that you may be able to use them
76 inside conditional constructs, provided the use does not resemble a
77 variable.
78
79 For example, to get a value surrounded by {}, the following will not
80 work:
81
82 {{$Var1}}
83
84 However, this will:
85
86 {?Var1 {[$Var1]}}
87
88 * One cannot have nested variables.
89
90 * Conditionals are limited to testing whether or not the variable has
91 a value. If you want more elaborate tests, or tests on more than one
92 value, you'll have to write a function to do it, and use the
93 {&function()} construct.
94
95 * Function arguments (as given with the {&funcname(arg1,arg2...)}
96 format) cannot have commas in them, since commas are used to separate
97 the arguments.
98
99 Justification For Existence
100
101 When I was writing SQLite::Work, I originally tried using
102 Text::Template (my favourite template engine) and also tried
103 Text::FillIn. Both of them had some lovely, powerful features.
104 Unfortunately, they were also relatively slow. In testing them with a
105 700-row table, using Text::Template took about 15 seconds to generate
106 the report, and using Text::FillIn took 45 seconds! Rolling my own very
107 simple template engine cut the time down to about 7 seconds.
108
109 The reasons for this aren't that surprising. Because Text::Template is
110 basically an embedded Perl engine, it has to run the interpreter on
111 each substitution. And Text::FillIn has a lot to do, what with being
112 very generic and very recursive.
113
114 The trade-off for the speed-gain of Text::NeatTemplate is that it is
115 quite simple. There is no nesting or recursion, there are no loops. But
116 I do think I've managed to grab some of the nicer features of other
117 template engines, such as limited conditionals, and formatting, and,
118 the most powerful of all, calling external functions.
119
120 This is a middleweight engine rather than a lightweight one, because I
121 needed more than just simple variable substitution, such as one has
122 with Template::Trivial. I consider the trade-off worth it, and others
123 might also, so I made this a separate module.
124
125FORMATTING
126
127 As well as simple substitution, this module can apply formatting to
128 values before they are displayed.
129
130 For example:
131
132 {$Money:dollars}
133
134 will give the value of the Money variable formatted as a dollar value.
135
136 Formatting directives are:
137
138 alpha
139
140 Convert to a string containing only alphanumeric characters (useful
141 for anchors or filenames)
142
143 alphadash
144
145 Convert to a string containing alphanumeric characters, dashes and
146 underscores; spaces are converted to underscores. (useful for anchors
147 or filenames)
148
149 comma_front
150
151 Put anything after the last comma at the front (as with an author
152 name) For example, "Smith,Sarah Jane" becomes "Sarah Jane Smith".
153
154 dollars
155
156 Return as a dollar value (float of precision 2)
157
158 email
159
160 Convert to a HTML mailto link.
161
162 float
163
164 Convert to float.
165
166 hmail
167
168 Convert to a "humanized" version of the email, with the @ and '.'
169 replaced with "at" and "dot". This is useful to prevent spambots
170 harvesting email addresses.
171
172 html
173
174 Convert to simple HTML (simple formatting)
175
176 int
177
178 Convert to integer
179
180 itemnum
181
182 Assume that the value is multiple values separated by the "pipe"
183 symbol (|) and select the item with an index of num (starting at
184 zero)
185
186 items_directive
187
188 Assume that the value is multiple values separated by the "pipe"
189 symbol (|) and split the values into an array, apply the directive
190 directive to them, and join them together with a space.
191
192 itemsjslash_directive
193
194 Like items_directive, but the results are joined together with a
195 slash between them.
196
197 itemslashnum
198
199 Assume that the value is multiple values separated by the "slash"
200 symbol (/) and select the item with an index of num (starting at
201 zero) Good for selecting out components of pathnames.
202
203 lower
204
205 Convert to lower case.
206
207 month
208
209 Convert the number value to an English month name.
210
211 namedalpha
212
213 Similar to 'alpha', but prepends the 'name' of the value. Assumes
214 that the name is only alphanumeric.
215
216 nth
217
218 Convert the number value to a N-th value. Numbers ending with 1 have
219 'st' appended, 2 have 'nd' appended, 3 have 'rd' appended, and
220 everything else has 'th' appended.
221
222 percent
223
224 Show as if the value is a percentage.
225
226 pipetocomma
227
228 Assume that the value is multiple values separated by the "pipe"
229 symbol (|) and replace those with a comma and space.
230
231 pipetoslash
232
233 Assume that the value is multiple values separated by the "pipe"
234 symbol (|) and replace those with a forward slash (/).
235
236 proper
237
238 Convert to a Proper Noun.
239
240 string
241
242 Return the value with no change.
243
244 title
245
246 Put any trailing ",The" ",A" or ",An" at the front (as this is a
247 title)
248
249 truncatenum
250
251 Truncate to num length.
252
253 upper
254
255 Convert to upper case.
256
257 url
258
259 Convert to a HTML href link.
260
261 wikilink
262
263 Format the value as the most common kind of wikilink, that is
264 [[value]]
265
266 wordsnum
267
268 Give the first num words of the value.
269
270CLASS METHODS
271
272 new
273
274 my $tobj = Text::NeatTemplate->new();
275
276 Make a new template object.
277
278METHODS
279
280 fill_in
281
282 Fill in the given values.
283
284 $result = $tobj->fill_in(data_hash=>\%data,
285 show_names=>\%names,
286 template=>$text);
287
288 The 'data_hash' is a hash containing names and values.
289
290 The 'show_names' is a hash saying which of these "variable names" ought
291 to be displayed, and which suppressed. This can be useful if you want
292 to use a more generic template, and then dynamically suppress certain
293 values at runtime.
294
295 The 'template' is the text of the template.
296
297 get_varnames
298
299 Find variable names inside the given template.
300
301 @varnames = $tobj->get_varnames(template=>$text);
302
303 do_replace
304
305 Replace the given value.
306
307 $val = $tobj->do_replace(targ=>$targ,
308 data_hash=>$data_hashref,
309 show_names=>\%show_names);
310
311 Where 'targ' is the target value, which is either a variable target, or
312 a conditional target.
313
314 The 'data_hash' is a hash containing names and values.
315
316 The 'show_names' is a hash saying which of these "variable names" ought
317 to be displayed, and which suppressed.
318
319 This can do templating by using the exec ability of substitution, for
320 example:
321
322 $out =~ s/{([^}]+)}/$tobj->do_replace(data_hash=>$data_hash,targ=>$1)/eg;
323
324 get_value
325
326 $val = $tobj->get_value(val_id=>$val_id, data_hash=>$data_hashref,
327 show_names=>\%show_names);
328
329 Get and format the given value.
330
331 convert_value
332
333 my $val = $tobj->convert_value(value=>$val,
334 format=>$format,
335 name=>$name);
336
337 Convert a value according to the given formatting directive.
338
339 See "FORMATTING" for details of all the formatting directives.
340
341 simple_html
342
343 $val = $tobj->simple_html($val);
344
345 Do a simple HTML conversion of the value. bold, italic, <br>
346
347Callable Functions
348
349 safe_backtick
350
351 {&safe_backtick(myprog,arg1,arg2...argN)}
352
353 Return the results of a program, without risking evil shell calls. This
354 requires that the program and the arguments to that program be given
355 separately.
356
357 format_items
358
359 {&format_items(fieldname,value,delim,outdelim,format,prefix,suffix)}
360
361 Format a field made of multiple items.
362
363REQUIRES
364
365 Test::More
366
367INSTALLATION
368
369 To install this module, run the following commands:
370
371 perl Build.PL
372 ./Build
373 ./Build test
374 ./Build install
375
376 Or, if you're on a platform (like DOS or Windows) that doesn't like the
377 "./" notation, you can do this:
378
379 perl Build.PL
380 perl Build
381 perl Build test
382 perl Build install
383
384 In order to install somewhere other than the default, such as in a
385 directory under your home directory, like "/home/fred/perl" go
386
387 perl Build.PL --install_base /home/fred/perl
388
389 as the first step instead.
390
391 This will install the files underneath /home/fred/perl.
392
393 You will then need to make sure that you alter the PERL5LIB variable to
394 find the module.
395
396 Therefore you will need to change the PERL5LIB variable to add
397 /home/fred/perl/lib
398
399 PERL5LIB=/home/fred/perl/lib:${PERL5LIB}
400
401SEE ALSO
402
403 Text::Template Text::FillIn Text::QuickTemplate Template::Trivial
404 Template::Toolkit HTML::Template
405
406BUGS
407
408 Please report any bugs or feature requests to the author.
409
410AUTHOR
411
412 Kathryn Andersen (RUBYKAT)
413 perlkat AT katspace dot com
414 http://www.katspace.org/tools
415
416COPYRIGHT AND LICENCE
417
418 Copyright (c) 2006 by Kathryn Andersen
419
420 This program is free software; you can redistribute it and/or modify it
421 under the same terms as Perl itself.
422
423
README.mkdn
1# NAME
2
3Text::NeatTemplate - a fast, middleweight template engine.
4
5# VERSION
6
7version 0.1101
8
9# SYNOPSIS
10
11 use Text::NeatTemplate;
12
13 my $tobj = Text::NeatTemplate->new();
14
15 $result = $tobj->fill_in(data_hash=>\%data,
16 show_names=>\%names,
17 template=>$text);
18
19# DESCRIPTION
20
21This module provides a simple, middleweight but fast template engine,
22for when you need speed rather than complex features, yet need more features
23than simple variable substitution.
24
25## Markup Format
26
27The markup format is as follows:
28
29- {$varname}
30
31 A variable; will display the value of the variable, or nothing if
32 that value is empty.
33
34- {$varname:format}
35
36 A formatted variable; will apply the formatting directive(s) to
37 the value before displaying it.
38
39- {?varname stuff \[$varname\] more stuff}
40
41 A conditional. If the value of 'varname' is not empty, this will
42 display "stuff value-of-variable more stuff"; otherwise it displays
43 nothing.
44
45 {?var1 stuff [$var1] thing [$var2]}
46
47 This would use both the values of var1 and var2 if var1 is not
48 empty.
49
50- {?varname stuff \[$varname\] more stuff!!other stuff}
51
52 A conditional with "else". If the value of 'varname' is not empty, this
53 will display "stuff value-of-variable more stuff"; otherwise it displays
54 "other stuff".
55
56 This version can likewise use multiple variables in its display parts.
57
58 {?var1 stuff [$var1] thing [$var2]!![$var3]}
59
60- {&funcname(arg1,...,argN)}
61
62 Call a function with the given args; the return value of the
63 function will be what is put in its place.
64
65 {&MyPackage::myfunc(stuff,[$var1])}
66
67 This would call the function myfunc in the package MyPackage, with the
68 arguments "stuff", and the value of var1.
69
70 Note, of course, that if you have a more complicated function and
71 are processing much data, this will slow things down.
72
73## Limitations
74
75To make the parsing simpler (and therefore faster) there are certain
76restrictions in what this module can do:
77
78- One cannot escape '{' '}' '\[' or '\]' characters. However, the substitution
79is clever enough so that you may be able to use them inside conditional
80constructs, provided the use does not resemble a variable.
81
82 For example, to get a value surrounded by {}, the following
83 will not work:
84
85 {{$Var1}}
86
87 However, this will:
88
89 {?Var1 {\[$Var1\]}}
90
91- One cannot have nested variables.
92- Conditionals are limited to testing whether or not the variable
93has a value. If you want more elaborate tests, or tests on more
94than one value, you'll have to write a function to do it, and
95use the {&function()} construct.
96- Function arguments (as given with the {&funcname(arg1,arg2...)} format)
97cannot have commas in them, since commas are used to separate the
98arguments.
99
100## Justification For Existence
101
102When I was writing SQLite::Work, I originally tried using [Text::Template](https://metacpan.org/pod/Text::Template)
103(my favourite template engine) and also tried [Text::FillIn](https://metacpan.org/pod/Text::FillIn). Both
104of them had some lovely, powerful features. Unfortunately, they were
105also relatively slow. In testing them with a 700-row table, using
106Text::Template took about 15 seconds to generate the report, and using
107Text::FillIn took 45 seconds! Rolling my own very simple template
108engine cut the time down to about 7 seconds.
109
110The reasons for this aren't that surprising. Because Text::Template
111is basically an embedded Perl engine, it has to run the interpreter
112on each substitution. And Text::FillIn has a lot to do, what with being
113very generic and very recursive.
114
115The trade-off for the speed-gain of Text::NeatTemplate is that
116it is quite simple. There is no nesting or recursion, there are
117no loops. But I do think I've managed to grab some of the nicer features
118of other template engines, such as limited conditionals, and formatting,
119and, the most powerful of all, calling external functions.
120
121This is a middleweight engine rather than a lightweight one, because
122I needed more than just simple variable substitution, such as one
123has with [Template::Trivial](https://metacpan.org/pod/Template::Trivial). I consider the trade-off worth it,
124and others might also, so I made this a separate module.
125
126# FORMATTING
127
128As well as simple substitution, this module can apply formatting
129to values before they are displayed.
130
131For example:
132
133{$Money:dollars}
134
135will give the value of the _Money_ variable formatted as a dollar value.
136
137Formatting directives are:
138
139- alpha
140
141 Convert to a string containing only alphanumeric characters
142 (useful for anchors or filenames)
143
144- alphadash
145
146 Convert to a string containing alphanumeric characters, dashes
147 and underscores; spaces are converted to underscores.
148 (useful for anchors or filenames)
149
150- comma\_front
151
152 Put anything after the last comma at the front (as with an author name)
153 For example, "Smith,Sarah Jane" becomes "Sarah Jane Smith".
154
155- dollars
156
157 Return as a dollar value (float of precision 2)
158
159- email
160
161 Convert to a HTML mailto link.
162
163- float
164
165 Convert to float.
166
167- hmail
168
169 Convert to a "humanized" version of the email, with the @ and '.'
170 replaced with "at" and "dot". This is useful to prevent spambots
171 harvesting email addresses.
172
173- html
174
175 Convert to simple HTML (simple formatting)
176
177- int
178
179 Convert to integer
180
181- item_num_
182
183 Assume that the value is multiple values separated by the "pipe" symbol (|) and
184 select the item with an index of _num_ (starting at zero)
185
186- items\__directive_
187
188 Assume that the value is multiple values separated by the "pipe" symbol (|) and
189 split the values into an array, apply the _directive_ directive to them, and
190 join them together with a space.
191
192- itemsjslash\__directive_
193
194 Like items\__directive_, but the results are joined together with a slash between them.
195
196- itemslash_num_
197
198 Assume that the value is multiple values separated by the "slash" symbol (/) and
199 select the item with an index of _num_ (starting at zero)
200 Good for selecting out components of pathnames.
201
202- lower
203
204 Convert to lower case.
205
206- month
207
208 Convert the number value to an English month name.
209
210- namedalpha
211
212 Similar to 'alpha', but prepends the 'name' of the value.
213 Assumes that the name is only alphanumeric.
214
215- nth
216
217 Convert the number value to a N-th value. Numbers ending with 1 have 'st'
218 appended, 2 have 'nd' appended, 3 have 'rd' appended, and everything
219 else has 'th' appended.
220
221- percent
222
223 Show as if the value is a percentage.
224
225- pipetocomma
226
227 Assume that the value is multiple values separated by the "pipe" symbol (|) and replace
228 those with a comma and space.
229
230- pipetoslash
231
232 Assume that the value is multiple values separated by the "pipe" symbol (|) and replace
233 those with a forward slash (/).
234
235- proper
236
237 Convert to a Proper Noun.
238
239- string
240
241 Return the value with no change.
242
243- title
244
245 Put any trailing ",The" ",A" or ",An" at the front (as this is a title)
246
247- truncate_num_
248
249 Truncate to _num_ length.
250
251- upper
252
253 Convert to upper case.
254
255- url
256
257 Convert to a HTML href link.
258
259- wikilink
260
261 Format the value as the most common kind of wikilink, that is \[\[_value_\]\]
262
263- words_num_
264
265 Give the first _num_ words of the value.
266
267# CLASS METHODS
268
269## new
270
271my $tobj = Text::NeatTemplate->new();
272
273Make a new template object.
274
275# METHODS
276
277## fill\_in
278
279Fill in the given values.
280
281 $result = $tobj->fill_in(data_hash=>\%data,
282 show_names=>\%names,
283 template=>$text);
284
285The 'data\_hash' is a hash containing names and values.
286
287The 'show\_names' is a hash saying which of these "variable names"
288ought to be displayed, and which suppressed. This can be useful
289if you want to use a more generic template, and then dynamically
290suppress certain values at runtime.
291
292The 'template' is the text of the template.
293
294## get\_varnames
295
296Find variable names inside the given template.
297
298 @varnames = $tobj->get_varnames(template=>$text);
299
300## do\_replace
301
302Replace the given value.
303
304 $val = $tobj->do_replace(targ=>$targ,
305 data_hash=>$data_hashref,
306 show_names=>\%show_names);
307
308Where 'targ' is the target value, which is either a variable target,
309or a conditional target.
310
311The 'data\_hash' is a hash containing names and values.
312
313The 'show\_names' is a hash saying which of these "variable names"
314ought to be displayed, and which suppressed.
315
316This can do templating by using the exec ability of substitution, for
317example:
318
319 $out =~ s/{([^}]+)}/$tobj->do_replace(data_hash=>$data_hash,targ=>$1)/eg;
320
321## get\_value
322
323$val = $tobj->get\_value(val\_id=>$val\_id,
324 data\_hash=>$data\_hashref,
325 show\_names=>\\%show\_names);
326
327Get and format the given value.
328
329## convert\_value
330
331 my $val = $tobj->convert_value(value=>$val,
332 format=>$format,
333 name=>$name);
334
335Convert a value according to the given formatting directive.
336
337See ["FORMATTING"](#formatting) for details of all the formatting directives.
338
339## simple\_html
340
341$val = $tobj->simple\_html($val);
342
343Do a simple HTML conversion of the value.
344bold, italic, <br>
345
346# Callable Functions
347
348## safe\_backtick
349
350{&safe\_backtick(myprog,arg1,arg2...argN)}
351
352Return the results of a program, without risking evil shell calls.
353This requires that the program and the arguments to that program
354be given separately.
355
356## format\_items
357
358{&format\_items(fieldname,value,delim,outdelim,format,prefix,suffix)}
359
360Format a field made of multiple items.
361
362# REQUIRES
363
364 Test::More
365
366# INSTALLATION
367
368To install this module, run the following commands:
369
370 perl Build.PL
371 ./Build
372 ./Build test
373 ./Build install
374
375Or, if you're on a platform (like DOS or Windows) that doesn't like the
376"./" notation, you can do this:
377
378 perl Build.PL
379 perl Build
380 perl Build test
381 perl Build install
382
383In order to install somewhere other than the default, such as
384in a directory under your home directory, like "/home/fred/perl"
385go
386
387 perl Build.PL --install_base /home/fred/perl
388
389as the first step instead.
390
391This will install the files underneath /home/fred/perl.
392
393You will then need to make sure that you alter the PERL5LIB variable to
394find the module.
395
396Therefore you will need to change the PERL5LIB variable to add
397/home/fred/perl/lib
398
399 PERL5LIB=/home/fred/perl/lib:${PERL5LIB}
400
401# SEE ALSO
402
403[Text::Template](https://metacpan.org/pod/Text::Template)
404[Text::FillIn](https://metacpan.org/pod/Text::FillIn)
405[Text::QuickTemplate](https://metacpan.org/pod/Text::QuickTemplate)
406[Template::Trivial](https://metacpan.org/pod/Template::Trivial)
407[Template::Toolkit](https://metacpan.org/pod/Template::Toolkit)
408[HTML::Template](https://metacpan.org/pod/HTML::Template)
409
410# BUGS
411
412Please report any bugs or feature requests to the author.
413
414# AUTHOR
415
416 Kathryn Andersen (RUBYKAT)
417 perlkat AT katspace dot com
418 http://www.katspace.org/tools
419
420# COPYRIGHT AND LICENCE
421
422Copyright (c) 2006 by Kathryn Andersen
423
424This program is free software; you can redistribute it and/or modify it
425under the same terms as Perl itself.
426