[Users] new feature: pseudo-variable transformations - sr-users

2 Feb 2007


      Hello,
currently in CVS trunk of development version is a new feature 
'transformations'. A transformations is basically a function that can be 
applied to a pseudo-variable (PV). In this way, the value of PV is not 
altered but the result is something different.
They are intended to facilitate access to different attributes of PV 
(like strlen of value, parts of value, substrings) or complete different 
value of PV (encoded in hexa, md5 value, escape/unescape PV value for DB 
operations...).
The format is '{id[,parameters]}' and they can be used inside parenthesis of pseudo-variables (note that even short name pseudo-variables must be enclosed in '(' and ')' to be able to apply transformations)
For example:
     - $(ru{s.len}) - returns the lenth of R-URI
     - $(avp(i:3){s.md5}) - returns the md5 string over value of $avp(i:3)
The following classes of transformations are implemented
1) string - the name of transformation starts with 's.'. Available transformations in this class:
- {s.len} - returns strlen of PV value
          - {s.md5} - returs md5 over PV value
          - {s.substr,offset,length} - returns substring starting at offset having
          size of 'length'. If offset is negative, then it is counted from the end of
          PV value, -1 being the last char. In case of positive value, 0 is first
          char. Length must be positive, in case of 0, substring to the end of
          PV value is returned. offset and length can be PV as well. Example:
          "abcd"{s.substr,1,0} = "bcd"
          - {s.select,index,separator} - returns a field from PV value. The field is
          selected based on separator and index. The separator must be a character
          used to identify the fields. Index must be a integer value or a PV. If
          index is negative, the count of fields starts from end of PV value, -1
          being last field. If index is positive, 0 is the first field. Example:
          "12,34,56"{s.select,1,,} = "34" ; "12,34,56"{s.select,-2,,} = "12"
          - {s.encode.hexa} - returns encoding in hexa of PV value
          - {s.decode.hexa} - returns decoding from hexa of PV value
          - {s.escape.common} - returns escaped string of PV value. Characters escaped
          are ''', '"', '' and 0. Useful when doing DB queries (care should be
          taken for non latin character set)
          - {s.unescape.common} - returns unescaped string of PV value. Reverse of
          above transformation.
2) uri - the name of transformation starts with 'uri.'. The PV value is considered to be a SIP URI. This transformation returns parts of SIP URI (see struct sip_uri). Available transformations in this class:
- {uri.user} - returns the user part
          - {uri.host} or {uri.domain} - returns the domain part
          - {uri.passwd} - returns the password
          - {uri.port} - returns the port
          - {uri.params} - returns the URI parameters in a string
          - {uri.param,name} - returns the value of parameter with name 'name'
          - {uri.headers} - returns URI headers
          - {uri.transport} - returns the value of transport parameter
          - {uri.ttl} - returns the value of ttl parameter
          - {uri.uparam} - returns the value of user parameter
          - {uri.maddr} - returns the value of maddr parameter
          - {uri.method} - returns the value of method parameter
          - {uri.lr} - returns the value of lr parameter
          - {uri.r2} - returns the value of r2 parameter
3) parameters list - the name of the transformation starts with 'param.'. The PV value is considered to be a string like "name1=value1;name2=value2;...". The transformations returns the value for a specific parameter, or the name of a parameter at a specific index. Available transformations in this class:
- {param.value,name} - returns the value of parameter 'name'
          Example: "a=1;b=2;c=3"{param.value,c} = "3"
          - {param.name,index} - returns the name of parameter at position 'index'.
          Example: "a=1;b=2;c=3"{param.name,1} = "b"
Within a PV, many transformation can be applied, being executed from left to right. Example:
          $var(x) = "a=1;b=22;c=333";
          $(var(x){param.value,$(var(x){param.name,1})}{s.len}) = 2
          - the length of the value of parameter at position 1 (remember 0 is first
          position, 1 is second position)
The transformations can be used anywhere, being considered parts of PV -- in xlog, avpops or other modules' functions and parameters, in right side assignment expressions or in comparisons.
Documentation page for transformations was opened at:
http://openser.org/dokuwiki/doku.php/transformations:devel
Feedback is welcome!
Cheers,
Daniel