Description:
A Pi3Expression is a general purpose expression syntax for efficient dynamic creation of text based on varied criteria. The expression takes the form of a sequence of text characters with some control characters which modify the meaning of the text which follows them. A Pi3Expression does not have to be enclosed in quotes but often will be quoted in configuration files to deliniate the expression from other configuration components. For illustration all examples used here will enclose the example expression in double-quotations ("").

Components:

Overview

Component	Syntax	Short Description	Example Expression	Example Result
String	Any character except $,%,&	Plain text	"Hello, World!"	Hello, World!
Escape Sequences	\c, where c is any character	Escaped charcaters, like printf format	"Line1\nLine2"	Line1 Line2
Literal	'any characters'	Literal text, characters not interpreted.	"The percent character is '%'"	The percent character is %
Parameter	%c, where c is a letter	A parameter, value depends on Pi3Expression context	"Parameter value of parameter ''v'' is ''%v''"	Parameter value of parameter 'v' is 'john'
Shortcut	$s, where s is a letter	A shortcut, shortcut value mappings are given below	"The current process id is $P"	The current process id is 24456
Functions	&FunctionName(Param1,Param2,..,ParamN)	A text processing function, described in 'Pi3Expression_Functions'	"Process id truncated to two characters is &trunc($P,2)"	Process id truncated to two characters is 24

Detailed Description of Components

String

Regular text that does not conform to other expression components is reproduced exactly if the expression result as in the expression string. The characters '(', ',', and ')' are considered normal characters outside a function context.

Escape Sequences

The escape or backslash character will be expanded to a control character in accordance with the following table:

Escape Sequence	Meaning
\a	Alert
\b	Backslash
\f	Form-feed
\n	New-line
\r	Carriage return
\t	Horizontal tab
\v	Vertical tab

Additionally any other character including characters with special meanings in Pi3Expressions ($,%,&,\,´) can be specified by placing ´\´ before them.

Literal

Character sequences enclosed in single quotes will be reproduced in the expression result as in the expression specification, but with the single quotes ommitted.

Parameter

The '%' character followed by a letter specifies a parameter. The value of a parameter depends on the evaluation context and should be documented along with the facility that uses the expression. Parameter characters are case sensitive.

Shortcut

The '$' character followed by a letter specifies a shortcut. Shortcut characters are case sensitive. The follow table gives shortcut mappings.

Shortcut	Evaluates to
$a	E-mail address of administrator (for current virtual host)
$A	IP Address of remote client
$b	Decimal representation of number of bytes sent to client this request
$c	Content-Type for this reponse
$C	Content-Type for this request (incoming)
$d	Debug flag, returns non-zero length string if debugging is on
$D	Handler time delta. Time spent in last handler object
$E	All error messages logged while handling this (sub)request
$f	Physical path to resource
$g	Indicate whether or not SSL is being used (HTTPS), (on/off)
$G	SSL secret key size
$h	Hostname of client
$H	Request HTTP protocol stamp
$i	Remoteident of client
$I	Path info section of client request URL
$k	Thread id of executing thread of execution
$K	SSL public key size
$l	Local IP address of connection
$m	Request method from client
$M	End of line sequence for the current operating system
$n	Name of current handler object
$N	Name of current handler phase
$o	Objectname of virtual host
$p	Port associated with this virtual host
$P	Process id
$q	Client query string
$r	Full uninterpreted request line from client
$R	Name of result code from last handler
$s	Current decimal HTTP response status code
$S	Server version stamp
$t	Time in common logfile format
$T	Elapsed since request context (PIHTTP) was created
$u	Remote username (from authentication)
$U	URL path of original request
$v	Hostname of virtual host
$x	Authentication type from is access was authenticated
$X	Depth of current request in subrequest hierarchy
$y	Content-Length: outgoing to client
$Y	Content-Length: incoming from client
$z	Script name
$Z	Path translated (url-unencoded path info)

Functions

The built-in text manipulation functions are described in the section 'Pi3Expression_Functions'.

Examples:

Expression	Process/Thread information [$P\|$k]
Evaluates to	Process/Thread information [24965\|23]

Expression	[$t]$h\|$r
Evaluates to	\|15/May/1997:21:30:16 +0000\|caught.evil.dom\|GET /../../etc/passwd HTTP/1.0

Name:
Pi3Expression_Functions

Description:
Pi3Expressions can use built in functions for text manipulation and conditional processing. These functions can be nested to perform complex evaluations. The built-in text processing functions are described here. Where text is interpreted as a numeric value, leading whitespace is skipped, then the text before the first non-digit is interpreted as a decimal number. Where text is interpreted as a boolean value, any non-zero length is considered 'true' and any text of length zero is considered 'false'.

Functions:

Overview

Note the following conventions used to describing these functions:
text - any text, e.g. "foo", "234'&'ad" number - text interpreted as a number, e.g. "5a" (interpreted as 5). [field] - an optional argument value1|value2 - either "value1" or "value2" as text, e.g left|right

Function Number of Arguments Syntax Short Description Example Expression Example Result
trunc 2 &trunc(text,number) Truncate text to length of number "&trunc(0123,2)" "01"
align 2..4 &align(text,number,[left|right],[padding]) Align text within a field "&align(0123,7)" "Line1"
"Line2"
dblookup 3..7 &dblookup(dbname,type,variable,[flags],[fnvalue],[first],[last]) Lookup a value in an internal database "&dblookup(request,rfc822,Content-Type)" "application/x-www-form-urlencoded"
if 2..3 &if(boolean,true_text,false_text) Conditionally include text "&if(text,yes,no)"
"&if(,yes,no)" "yes"
"no"
not 1 &not(boolean) Negate boolean argument "&not(text)"
"&not()" ""
"true"
regexp 2 &regexp(regexp,text) Regular expression comparision "&regexp(j*n,john)"
"&regexp(b*l,john)" "true"
""
arg,_ 0..2 &_([index],number) Function argument "&_(0,0)"; &arg(1) context dependent
cmp 2 &cmp(text1,text2) String comparision "&cmp(hello,Hello)" ""
cmpi 2 &cmpi(text1,text2) String comparision case insensitive "&cmp(hello,Hello)" "true"

Function	Number of Arguments	Syntax	Short Description	Example Expression	Example Result
trunc	2	&trunc(text,number)	Truncate text to length of number	"&trunc(0123,2)"	"01"
align	2..4	&align(text,number,[left\|right],[padding])	Align text within a field	"&align(0123,7)"	"Line1" "Line2"
dblookup	3..7	&dblookup(dbname,type,variable,[flags],[fnvalue],[first],[last])	Lookup a value in an internal database	"&dblookup(request,rfc822,Content-Type)"	"application/x-www-form-urlencoded"
if	2..3	&if(boolean,true_text,false_text)	Conditionally include text	"&if(text,yes,no)" "&if(,yes,no)"	"yes" "no"
not	1	&not(boolean)	Negate boolean argument	"&not(text)" "&not()"	"" "true"
regexp	2	&regexp(regexp,text)	Regular expression comparision	"&regexp(jn,john)" "&regexp(bl,john)"	"true" ""
arg,_	0..2	&_([index],number)	Function argument	"&_(0,0)"; &arg(1)	context dependent
cmp	2	&cmp(text1,text2)	String comparision	"&cmp(hello,Hello)"	""
cmpi	2	&cmpi(text1,text2)	String comparision case insensitive	"&cmp(hello,Hello)"	"true"

Detailed Description of Functions

trunc(text,number)

Truncate text to the the decimal value of number.

align(text,length,left|right,padding)

Write text 'text' into a field of length characters, aligning to the left or right. The character sequence padding is repeated to fill out the field. The default alignment left. The default padding is spaces. If 'text' is longer than the value of 'length', it will not be truncated.

A field of exactly 'length' character can be ensured by using an expression like:
&align(&trunc(text is too big,10),10)

if(boolean,true_text,false_text)

If boolean is true (i.e., boolean is any character sequence with length greater than zero), then this function evaluates to true_text, otherwise this function evaluates to false_text.

not(boolean)

If boolean is true (i.e., boolean is any character sequence with length greater than zero), then this function returns a zero length text string (false), otherwise a non-zero length text string (true) is returned. The net result is the negation of the boolean argument.

regexp(regexp,text)

Determine if the regular expression 'regex' matches the text 'text'. Returns 'true' (non-empty text) on success, 'false' (empty text) on failure. Regular expression matching is done using the function HTTPUtil_regexMatch(), reference that function to see which regular expression constructs which are supported.

arg([index],[context])

This is a special function with meaning only within the context of another function which is iterating through a number of elements. The argument 'index' is the index of the argument from the enclosing function. The argument context is a number indicating the which enclosing functions context to use. Context 0 refers to the callees context, 1 to the callees callee etc.

dblookup(dbname,type,variable,[flags],[fnvalue],[first],[last])

NOTE:This function is not currently supported to the full specification as described here. Iterate over a number of elements of a specific type in a particular database.

Function arguments:

Argument position Description Default, (+)=Mandatory Values
1 name of database + program|connection|host|request|response
2 type of element opaque|rfc822|string,variable,[flags],[fncallback],[first],[last])
3 variable name a variable name or empty for all
4 db flags affecting lookup 0 pidbflag_propagateup|pidbflag_fastkey|0
5 callback argument &_() Expression invoked for value of every db entry
6 start index 0 Number
7 end index 0 Number

Argument position	Description	Default, (+)=Mandatory	Values
1	name of database	+	program\|connection\|host\|request\|response
2	type of element		opaque\|rfc822\|string,variable,[flags],[fncallback],[first],[last])
3	variable name		a variable name or empty for all
4	db flags affecting lookup	0	pidbflag_propagateup\|pidbflag_fastkey\|0
5	callback argument	&_()	Expression invoked for value of every db entry
6	start index	0	Number
7	end index	0	Number

abbrev(field,fieldlen,append)

This function is used to truncate text to a field if fieldlen characters appending text 'append' at the end of the field if it was truncated, this is useful for truncating test to fit in a field while given a clear indicatation if the field was concatenated.

cmp(text1,text2), cmpi(text1,text2)

Respectively case sensitive and insensitive comparision of two text patterns.

Examples:

Expression	Result
"&abbrev(Abcdef,7,...)"	"Abcdef"
"&abbrev(Abcdefg,7,...)"	"Abcdefg"
"&abbrev(Abcdefgh,7,...)"	"Abcd..."
"&abbrev(Abcdefghi,7,..)"	"Abcde.."