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 ("").


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
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

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.
Character sequences enclosed in single quotes will be reproduced in the expression result as in the expression specification, but with the single quotes ommitted.
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.
The '$' character followed by a letter specifies a shortcut. Shortcut characters are case sensitive. The follow table gives shortcut mappings.
ShortcutEvaluates to
$aE-mail address of administrator (for current virtual host)
$AIP Address of remote client
$bDecimal representation of number of bytes sent to client this request
$cContent-Type for this reponse
$CContent-Type for this request (incoming)
$dDebug flag, returns non-zero length string if debugging is on
$DHandler time delta. Time spent in last handler object
$EAll error messages logged while handling this (sub)request
$fPhysical path to resource
$gIndicate whether or not SSL is being used (HTTPS), (on/off)
$GSSL secret key size
$hHostname of client
$HRequest HTTP protocol stamp
$iRemoteident of client
$IPath info section of client request URL
$kThread id of executing thread of execution
$KSSL public key size
$lLocal IP address of connection
$mRequest method from client
$MEnd of line sequence for the current operating system
$nName of current handler object
$NName of current handler phase
$oObjectname of virtual host
$pPort associated with this virtual host
$PProcess id
$qClient query string
$rFull uninterpreted request line from client
$RName of result code from last handler
$sCurrent decimal HTTP response status code
$SServer version stamp
$tTime in common logfile format
$TElapsed since request context (PIHTTP) was created
$uRemote username (from authentication)
$UURL path of original request
$vHostname of virtual host
$xAuthentication type from is access was authenticated
$XDepth of current request in subrequest hierarchy
$yContent-Length: outgoing to client
$YContent-Length: incoming from client
$zScript name
$ZPath translated (url-unencoded path info)
The built-in text manipulation functions are described in the section 'Pi3Expression_Functions'.


ExpressionProcess/Thread information [$P|$k]
Evaluates toProcess/Thread information [24965|23]
Evaluates to|15/May/1997:21:30:16 +0000|caught.evil.dom|GET /../../etc/passwd HTTP/1.0



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'.



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"
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)"
not 1 &not(boolean) Negate boolean argument "&not(text)"
regexp 2 &regexp(regexp,text) Regular expression comparision "&regexp(j*n,john)"
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

Truncate text to the the decimal value of number.
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 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.
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.
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.
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.
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

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.


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