matched Expressions

The matched expression returns the mapping rule’s matched element’s local-name, namespace-prefix, namespace-uri, QName, or sequence number. This expression is useful to retrieve the name of the matched element in the case that a wildcard was used in the match expression, or to determine a unique identifier for an element. It is represented in the xfMap document with the <matched> element, and it has the following general form:

<matched expr=”...” ancestor=”...” path=”...” prefix-binding=”...”>
    <arg name=”ancestor”>...</arg>
    <arg name=”path”>...</arg>
    <arg name=”prefix-binding”>...</arg>
</matched> 

The expression string (that is, the expr attribute) specifies whether the local-name, the namespace-prefix, the namespace-uri, QName, or the sequence number of the matched element is to be returned. The valid values for the expression string are local-name, prefix, uri, qname, and sequence. The sequence number is a period-separated list of numbers which identify the path from the root of the xml tree to the child element where the matched expression is evaluated.

The ancestor attribute, or named argument, is optional. Its value indicates which ancestor element the expr attribute applies to. The valid values for the ancestor attribute are self, parent, grandparent, or a non-negative number, with self, parent, and grandparent being equivalent to 0, 1, and 2, respectively. The default value for the ancestor attribute is self.

The path attribute, or named argument, is also optional. When specified, the expression returns a path from an ancestor to self, where self is the matched element. The type of values in the path will be the same as the ones indicated in the expr attribute. Each component in the path is separated by a “/”. The path attribute’s value indicates the point from which the path being returned should begin. The valid values for the path attribute are self, parent, grandparent, root, or a non-negative number, with self, parent, and grandparent being equivalent to 0, 1, and 2, respectively and root being equal to the count from the matched element to the root. The default value for the path attribute is self.

The prefix-binding attribute, or named argument, is optional. It is only applicable when expr is set to prefix. The valid values for this attribute are dataset or xfMap. The default value for the prefix-binding attribute is dataset.

Example

three_players.xml

<?xml version="1.0" encoding="UTF-8"?>
<players xmlns="http://schemas.sports.com/players" 
         xmlns:pl2="http://schemas.sports.com/2/players"
         xmlns:pl3="http://schemas.sports.com/5/players">

   <Laura> <age>24</age> </Laura>      
   <pl2:Sharen> <age>27</age> </pl2:Sharen>
   <Claudia> <age>28</age> </Claudia>            

</players>

three_players.xmp

<?xml version="1.0" encoding="UTF-8"?>
<xfMap xmlns:pl="http://schemas.sports.com/players">      
   <feature-map>   
      <mapping match="pl:players/*">
         <feature-type> <literal expr="player"/> </feature-type>
         <attributes>
            <attribute>
               <name> <literal expr="local-name"/> </name>
               <value> <matched expr="local-name"/> </value>
            </attribute>
            <attribute>
               <name> <literal expr="ns-prefix"/> </name>
               <value> <matched expr="prefix"/> </value>
            </attribute>
            <attribute>
               <name> <literal expr="ns-uri"/> </name>
               <value> <matched expr="uri"/> </value>
            </attribute>
            <attribute>
               <name> <literal expr="QName"/> </name>
               <value> <matched expr="qname"/> </value>
            </attribute>    
            <attribute>
               <name> <literal expr="Sequence Number"/> </name>
               <value> <matched expr="sequence"/> </value>
            </attribute>                     
            <attribute>
               <name> <literal expr="Parent-QName"/> </name>
               <value> <matched expr="qname" ancestor=”parent”/> </value>
            </attribute>
         </attributes>                     
      </mapping>      
   </feature-map> 
</xfMap>

FME features constructed:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: `player'
Attribute(string): `QName' has value `Laura'
Attribute(string): `Sequence Number' has value `1.3'
Attribute(string): `local-name' has value `Laura'
Attribute(string): `ns-prefix' has value `'
Attribute(string): `ns-uri' has value `http://schemas.sports.com/players'
Attribute(string): `Parent-QName' has value `players'
Attribute(string): `xml_type' has value `xml_no_geom'
Geometry Type: Unknown (0)
===================================================================
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: `player'
Attribute(string): `QName' has value `pl2:Sharen'
Attribute(string): `local-name' has value `Sharen'
Attribute(string): `ns-prefix' has value `pl2'
Attribute(string): `ns-uri' has value `http://schemas.sports.com/2/players'
Attribute(string): `Parent-QName' has value `players'
Attribute(string): `xml_type' has value `xml_no_geom'
Geometry Type: Unknown (0)
===================================================================
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Feature Type: `player'
Attribute(string): `QName' has value `Claudia'
Attribute(string): `local-name' has value `Claudia'
Attribute(string): `ns-prefix' has value `'
Attribute(string): `ns-uri' has value `http://schemas.sports.com/players'
Attribute(string): `Parent-QName' has value `players'
Attribute(string): `xml_type' has value `xml_no_geom'
Geometry Type: Unknown (0)
===================================================================