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