TPLTALK

TplTalk (TemplateTalk) is an open standard programming interface for template
based content processing like cgi/form-processing or complex server-based editing
systems.



* TECHNICAL INFO

interface:
call:
parse(*input_hash,*template_array,*out_stream,*error_sub,GMToffsets_secs)
breaks to sub *error_sub(string,fatalflag)

streaming:
processes a given hash of vars/parameters agains a template.
results: modified param-hash, standard output in *out_stream,
erros will be returned to *error_sub (syntax and runtime errors will return
with fatalflag set to 1, breaks will return with fatalflag 0).


templates may contain the following TAGs:
all TAGs enclosed in <!--@ ... --> or <!-- @ ... -->
(white space compliant, not case sensitive, one statement per tag)

fields/vars are designated by [x] = value of param x.
nested, indexed or compound values allowed:
xmp:
	[a]=x
	[b]=a
	=> [[b]] == [a]
	=> [[a][b]] == [x[b]] == [xa]

SYNTAX:
values:
[x] ...  simple include (<!-- @[x] --> prints value of param/var "x")
[x] (+|-|*|/|%|.) <expression> ... compound include (prints result)
  <expression> may be any single designated or bare value or any
  simple arithmetic combination starting with a value.
	xmp: [x]+2, [x] + (2+[y])*8,

formated number output:
	[x] UNF ... universal number format (10000.0 => 10 000.0)
	[x] ENF ... european number format  (10000.0 => 10.000,0)

assignments:
[x] [+|-|.|/|%]= <expression> ... assignment to [x] 
	xmp: [x] *= 4+5, [x] = "word", [x]= ([y]+2) *10, [x]=5
[x] (++|--) .. increment|decrement [x]
[x] =~ <reg.exp. substitution> ... substitute with reg.exp.
	syntax is Perl syntax; no eval flag allowed.
	xmp: [x] =~ s/foo(\d+)/bar$1/
	     [x] =~ s/(foo|bar)[\d\w]\1/z/gi

if/else (may nest):
pattern: <!--@ IF <condition> --> foo <!--@ ELSIF <condition> --> bar 
         <!--@ELSE--> foobar <!--@ /IF -->
	!<condition> ... negative value of condition
	<condition> may be any of the following:
	[x] (<|>|<=|>=|==|!=|=) <expression> ... compare [x] and expression
	[x] (=~|!~) <reg. exp.> (p.e.: "<!--@ if [x] =~ /\bfoo\b/i -->")
	[x] ... simple test for existence ("","0" are false values)
	        <!--@ if ![x] --> ... test for negative existence
	[x] isnumber ... test for unsigned float or int, no white space
	[x] isint ... test for (signed) integer
	[x] isbareint ... test for unsigned integer
	[x] isfloat ... test for (signed) float
	[x] isbarefloat ... test for unsigned float
	[x] isreal ... same as "[x] isfloat"
	[x] ismail ... test for valid mail address

loops:
<!--@ WHILE <condition> --> foobar <!--@ /WHILE -->
	(use indexed fields as "[[x][y]]" or "[x[y]]" inside loops.)

format/round:
FORMAT [x] <pattern> ... formats [x] to printf-pattern
xmp:
	[x]=4
	format [x] %02d
	=> prints "04"

ROUND [x] n ... rounds and formats [x] to n fractions
	is n equal zero or n omitted [x] will be rounded to the next integer
	xmp:
	[x]=0.2
	round [x] 2
	=> prints "0.20" (same as '<!--@ format [x] %.2f -->')
	[x]=0.256
	round [x] 1
	=> prints "0.3"

others:
RAND [x] ... assign random 0 > n < 1 to [x]
BREAK errorstring ... break (with optional error message incl. values)
LIST ... dumps input-parameters in name:value pairs
DUMP ... dumps input-parameters without [xvar_...] params in [name]value pairs

date and time stamps (all GMT)
DATE ... full date (Mon. DD YYYY  HH.MM GMT)
GMTSTRING ... date (GMT-string)
YYYYMMDD ... date (YYYY/MM/DD)
DDMMYYYY ... date (DD.MM.YYYY)
HHMM ... time (HH:MM)
HHMMSS ... time (HH:MM:SS)

comments:
trailing '#', e.g.: <!--@ # comment -->

reservered parameters:
use [xvar_...] for control vars (won't be dumped, listed separately)
p.e.: [xvar_mailfunction], [xvar_mailto];



* SYNTAX EXAMPLES

# simple value tags:
Send me <!--@ [t-shirts] --> T-shirts.


# arithmetic expressions:
Send me <!--@ [t-shirts] --> T-shirts à EUR <!--@ [t-shirt-price] -->
for  EUR <!--@ [t-shirts] * [t-shirt-price] -->.


# assignments:
<!--@ [x] =27 -->
<!--@ [y] = (24*[x])+3 -->
<!--@ [z] = "this is [x] times" -->


# refernced values:
let's suppose [currency] holds the value 'ATS'
<!--@[ATS]=13.7603-->
Send me <!--@ [t-shirts] --> T-shirts à EUR <!--@ [t-shirt-price] -->
(<!--@ [currency] --> <!--@ [t-shirt-price]*[[currency]] -->)
for  EUR <!--@ [t-shirts] * [t-shirt-price] -->
(<!--@ [currency] --> <!--@ [t-shirts] * [t-shirt-price]*[[currency]] -->).

=> 'Send me 5 T-shirts à EUR 1.20 (ATS 16.51236) for EUR 6 (ATS 82.5618).'


# rounded values:
<!--@[ATS]=13.7603-->
<!--@ # round prices -->
<!--@[mypriece] = [t-shirt-price]*[[currency]] --><!-- ROUND [myprice] 2 -->
<!--@[mysum] = [myprice]*[t-shirts] --><!-- ROUND [myprice] 2 -->

Send me <!--@ [t-shirts] --> T-shirts à EUR <!--@ [t-shirt-price] -->
(<!--@ [currency] --> <!--@ [myprice] -->)
for  EUR <!--@ [t-shirts] * [t-shirt-price] -->
(<!--@ [currency] --> <!--@ [mysum] -->).

=> 'Send me 5 T-shirts à EUR 1.20 (ATS 16.51) for EUR 6 (ATS 82.55).'


# formated ouput:
<!--@ [x]=125300.1 -->
<!--@ FORMAT [x] %.2f -->
Formated: <!--@[x]--> UNF: <!--@[x] UNF --> ENF: <!--@[x] ENF -->

=> Formated: 125300.10 UNF: 125 300.10 ENF: 125.300,10


# conditions:
<!--@ if [val1] --> Yes, I want my T-shirt, I am paying by
	<!--@ if [val1_opt] = 1 -->creditcard
	<!--@ elsif [val1_opt] = 2 -->money order
	<!--@ elsif [val1_opt] = 3 -->cheque enclosed
	<!--@ elsif [val1_opt] = 4 -->other: <!--@ [val1_other] -->
	<!--@ else --><!--@ break "Paying option for [val1] required!"-->
	<!--@ /if -->.
<!--@ else --> No, I don't want no T-shirt.<!--@ /if -->

<!--@ if ![val2n] isbareint --><!--@ BREAK '[val2n]' is no integer! --><!--@ /if -->


# loops (indexed variables):
<!--@[x]=0-->
<!--@ while [x] <= 20 -->
	Article <!--[art[x]]-->:
	<!--@[y]=0-->
	<!--@ while [art[x]_opt[y]] -->
		Option <!--@ [y] -->: <!--@ [art[x]_opt[y]] -->
		<!--@ [y]++ -->
	<!--@ /while -->
	<!--@ [x]++ -->
<!--@ /while -->

or:

<!--@ [a]= art000 -->
<!-- while [[a]] -->Article <!--@ [[a]] --><!--@ [a]++ --><!--@ /while -->

or:
<!--@ [a]= art000 -->
<!-- while [[a]] -->Article <!--@ [[a]] -->:
	<!--@ [o]= opt000 -->
	<!--@ while [[a][o]] -->
		Option: <!--@ [[a][o]] -->
		<!--@ [o]++ -->
	<!--@ /while -->
	<!--@ [a]++ -->
<!--@ /while -->


# regular expressions
conditions:
<!--@ if [string] =~ /\bfuck\b/i --><!--@ break No filth! --><!--@ /if -->
<!--@ if [string] !~ /\b(yes|yep|yeah)\b/i --><!--@ break "Be positive!" --><!--@ /if -->

<!--@ if [mailsubject] =~ /\bjobs?\b/i -->
	<!--@ [xvar_mailaddress] = jobs@masswerk.at -->
<!--@ /if -->

substitutions:
<!--@ [string] =~ s/\bfuck\b/ZENSORED/gi -->
<!--@ [string] =~ s/(["'])(.*?)\1/\&quot;$2\&quot;/g -->


mass:werk / Norbert Landsteiner <http://www.masswerk.at> 10.1999