The tclexpr expression provides a limited set of Tcl processing capabilities on the expression sequences. It has the following general form:
<tclexpr expr=”...”> <arg> <!-- some expression sequence --> </arg> <arg> <!-- some expression sequence --> </arg> ... <arg> <!-- some expression sequence --> </arg> </tclexpr>
The value of this expression depends on the Tcl command that is specified through the expression string (i.e., the expr attribute); this also dictates the number of arguments (i.e., the <arg> elements) that the tclexpr expression should have.
The following lists the available Tcl commands and their arguments.
expr:
<tclexpr expr=”expr”> <arg> <!-- some expression sequence --> </arg> ... </tclexpr>
Concatenates all of the arguments and evaluates the result as a Tcl expression. The number of <arg> elements following the first one depends on which Tcl expression is specified.
concat:
<tclexpr expr=”concat”> <arg> <!-- arg0 --> </arg> ... <arg> <!-- argN --> </arg> </tclexpr>
Returns a concatenated list by treating all of the arguments arg0 to argN as lists.
join:
<tclexpr expr=”join”> <arg> <!-- source list --> </arg> <arg> <!-- (optional) join string --> </arg> </tclexpr>
Returns a string that is the concatenated elements of the source list. An optional join string may be specified to separate the concatenated elements. This join string defaults to a single space when it is not specified.
lindex:
<tclexpr expr=”lindex”> <arg> <!-- source list --> </arg> <arg> <!-- index --> </arg> </tclexpr>
Returns the index item from the source list. The index starts at 0, and can be ‘end’ so that it returns the last item of the source list.
linsert:
<tclexpr expr=”linsert”> <arg> <!-- source list --> </arg> <arg> <!-- index --> </arg> <arg> <!-- element0 --> </arg> ... <arg> <!-- elementN --> </arg> </tclexpr>
Insert the elements element0 ... elementN into the source list starting at the specified index. An index of 0 inserts at the beginning while an index of ‘end’ inserts at the end of the source list.
list:
<tclexpr expr=”list”> <arg> <!-- arg0 --> </arg> ... <arg> <!-- argN --> </arg> </tclexpr>
Returns a list containing the given arguments arg0 to argN.
llength:
<tclexpr expr=”llength”> <arg> <!-- source list --> </arg> </tclexpr>
Return the number of elements in the source list.
lrange:
<tclexpr expr=”lrange”> <arg> <!-- source list --> </arg> <arg> <!-- first --> </arg> <arg> <!-- last --> </arg> </tclexpr>
Returns a list consisting of the source list elements from indices first to last. The indices start from 0; the last index can be ‘end’ to refer to the last element of the source list.
lreplace:
<tclexpr expr=”lreplace”> <arg> <!-- source list --> </arg> <arg> <!-- first --> </arg> <arg> <!-- last --> </arg> <arg> <!-- element0 --> </arg> ... <arg> <!-- elementN --> </arg> </tclexpr>
Replaces the elements in the source list having the indices first through last with the given elements element0 ... elementN. If no elements are supplied, then the list elements within the indices are deleted.
lsearch:
<tclexpr expr=”lsearch”> <arg> <!-- (optional) search mode --> </arg> <arg> <!-- source list --> </arg> <arg> <!-- search pattern --> </arg> </tclexpr>
Searches the source list for an element that matches the search pattern. If it is found, it returns the index of the matching element in the source list; otherwise it returns -1. The valid values for the optional search mode are: -exact (use exact matching), -glob (use glob pattern matching), and -regexp (use regular expression matching).
lsort:
<tclexpr expr=”lsort”> <arg> <!-- (optional) sort options --> </arg> <arg> <!-- source list --> </arg> </tclexpr>
Sorts the elements in the source list. The valid values for the optional sort options are:
- ascii (sort by ASCII collation order)
- dictionary (sort by dictionary order)
- integer (compare elements as integers)
- real (compare elements as floating points)
- increasing (sort in increasing order)
- decreasing (sort in decreasing order)
split:
<tclexpr expr=”split”> <arg> <!-- source string --> </arg> <arg> <!-- (optional) separators --> </arg> </tclexpr>
Splits the source string into a Tcl list. The elements in the string are split if they are separated by any of the characters in separators. The separators argument is optional; when it is not specified, then the default separator is whitespace.
string:
<tclexpr expr=”string”> <arg> <!-- option --> </arg> ... </tclexpr>
Performs string operations based on option; this value also dictates the number of arguments that follow it.
The valid values for option are:
compare
<tclexpr expr=”string”> <arg> <literal expr=”compare”/> </arg> <arg> <!-- string1 --> </arg> <arg> <!-- string2 --> </arg> </tclexpr>
Compares the strings string1 and string2 lexicographically. Returns -1 if string1 is less than string2, 0 if equal, or 1 if greater.
first
<tclexpr expr=”string”> <arg> <literal expr=”first”/> </arg> <arg> <!-- string1 --> </arg> <arg> <!-- string2 --> </arg> </tclexpr>
Returns the index of the first occurrence of string1 in string2, or -1 if there are no occurrences.
index
<tclexpr expr=”string”> <arg> <literal expr=”index”/> </arg> <arg> <!-- source string --> </arg> <arg> <!-- char index --> </arg> </tclexpr>
Returns the character in source string that has index char index, else the empty string is returned if char index is out of range.
last
<tclexpr expr=”string”> <arg> <literal expr=”last”/> </arg> <arg> <!-- string1 --> </arg> <arg> <!-- string2 --> </arg> </tclexpr>
Returns the index of the last occurrence of string1 in string2, else -1 if there are no occurrences.
length
<tclexpr expr=”string”> <arg> <literal expr=”length”/> </arg> <arg> <!-- source string --> </arg> </tclexpr>
Returns the length of the source string.
match
<tclexpr expr=”string”> <arg> <literal expr=”match”/> </arg> <arg> <!-- pattern --> </arg> <arg> <!-- source string --> </arg> </tclexpr>
Returns 1 if the source string matches the glob pattern, else 0 is returned.
range
<tclexpr expr=”string”> <arg> <literal expr=”range”/> </arg> <arg> <!-- source string --> </arg> <arg> <!-- first --> </arg> <arg> <!-- last --> </arg> </tclexpr>
Returns the substring of source string consisting of the characters from the index first through the index last. last can be the string ‘end’.
tolower
<tclexpr expr=”string”> <arg> <literal expr=”tolower”/> </arg> <arg> <!-- source string --> </arg> </tclexpr>
Returns the source string converted to lowercase.
toupper
<tclexpr expr=”string”> <arg> <literal expr=”toupper”/> </arg> <arg> <!-- source string --> </arg> </tclexpr>
Returns the source string converted to uppercase.
trim
<tclexpr expr=”string”> <arg> <literal expr=”trim”/> </arg> <arg> <!-- source string --> </arg> <arg> <!-- (optional) chars to trim --> </arg> </tclexpr>
Returns the source string with the leading and trailing characters from the set chars to trim removed. The chars to trim argument is optional; when it is not specified, it defaults to the whitespace characters.
trimleft
<tclexpr expr=”string”> <arg> <literal expr=”trimleft”/> </arg> <arg> <!-- source string --> </arg> <arg> <!-- (optional) chars to trim --> </arg> </tclexpr>
Returns the source string with the leading characters from the set chars to trim removed. The chars to trim argument is optional; when it is not specified, it defaults to the whitespace characters.
trimright
<tclexpr expr=”string”> <arg> <literal expr=”trimright”/> </arg> <arg> <!-- source string --> </arg> <arg> <!-- (optional) chars to trim --> </arg> </tclexpr>
Returns the source string with the trailing characters from the set chars to trim removed. The chars to trim argument is optional; when it is not specified, it defaults to the whitespace characters.
wordend
<tclexpr expr=”string”> <arg> <literal expr=”wordend”/> </arg> <arg> <!-- source string --> </arg> <arg> <!-- index --> </arg> </tclexpr>
Returns the index after a word for which index falls in the source string. A word is assumed to be delimited by whitespace.
wordstart
<tclexpr expr=”string”> <arg> <literal expr=”wordstart”/> </arg> <arg> <!-- source string --> </arg> <arg> <!-- index --> </arg> </tclexpr>
Returns the index before a word for which index falls in the source string. A word is assumed to be delimited by whitespace.
Example
The example below illustrates several of the tclexpr expression operations. Please refer to the comments in the tclexpr.xmp for details.
tclexpr.xml
<?xml version=”1.0”?> <strings> <str1>faerie</str1> <str2>queene</str2> <str3>the</str3> </strings>
tclexpr.xmp
<?xml version="1.0" encoding="UTF-8"?>
<xfMap>
<feature-map>
<mapping match="strings">
<define>
<let name="str1"> <extract expr="./str1"/> </let>
<let name="str2"> <extract expr="./str2"/> </let>
<let name="str3"> <extract expr="./str3"/> </let>
<let name="theList">
<literal expr='"'/>
<tclexpr expr="list">
<arg> <defnval expr="str3"/> </arg>
<arg> <defnval expr="str1"/> </arg>
<arg> <defnval expr="str2"/> </arg>
</tclexpr>
<literal expr='"'/>
</let>
</define>
<feature-type> <defnval expr="theList"/> </feature-type>
<attributes>
<attribute>
<name> <literal expr="list-length"/> </name>
<value>
<tclexpr expr="llength">
<arg> <defnval expr="theList"/> </arg>
</tclexpr>
</value>
</attribute>
<attribute>
<name> <literal expr="sorted-list"/> </name>
<value>
<tclexpr expr="lsort">
<arg> <defnval expr="theList"/> </arg>
</tclexpr>
</value>
</attribute>
<attribute>
<name> <literal expr="eval-expr(1+3+4+3+1)"/> </name>
<value>
<tclexpr expr="expr">
<arg> <literal expr="1+3+4+3+1"/> </arg>
</tclexpr>
</value>
</attribute>
<attribute>
<name> <literal expr="upcase"/> </name>
<value>
<tclexpr expr="string">
<arg> <literal expr="toupper"/> </arg>
<arg> <defnval expr="theList"/> </arg>
</tclexpr>
</value>
</attribute>
</attributes>
</mapping>
</feature-map>
</xfMap>
FME feature constructed:
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Feature Type: `"the faerie queene"' Attribute: `eval-expr(1+3+4+3+1)' has value `12' Attribute: `list-length' has value `3' Attribute: `sorted-list' has value `faerie queene the' Attribute: `upcase' has value `THE FAERIE QUEENE' Attribute: `xml_type' has value `xml_no_geom' Geometry Type: Unknown (0) ================================================================