The arrays returned by XML_PullParser's tokenizing functions are "flat", i.e. while they are multi-dimensional, they are not tree-structured and are addressed sequentially by index number. (See Appendix 1. ) A token will include the parent and all of its children, if any. XML_PullParser needs ways to separate out or "select" the precise element and its attributes which the code calls for, and it provides both techniques and class methods which will do this. These techniques and methods are equivalent to selectors in XSL style-sheets. In this Introduction, we'll look first at an obvious technique and then at a useful class method.

What if in Listing 6 we wanted to include the domain name in addition to the IP address? The "domain" element would then be added to the $tags array.

Listing 7

        1.   $child_tags = array();
        2.   $tags = array("ipaddress", "domain");
        3.   $parser = new XML_PullParser("DNS.xml",$tags,$child_tags);
        4.
        5.   while($token = $parser->XML_PullParser_getToken())
        6.   {
        7.     if($ip = $parser->XML_PullParser_getText('ipaddress')) {
        8.       echo "IP address: " . $ip ."\n";
        9.    }
       10.   if($domain = $parser->XML_PullParser_getText('domain')) {
       11.       echo "Domain Name: " . $domain ."\n\n";
       12.    }
       13.   }

 /*
  Result
        IP address: 172.20.19.6
        Domain Name:  example.com
 */

This code takes advantage of a standard protocol in XML_PullParser, which is to return the Null value or an empty string or array when there is no result. We test for the return value of XML_PullParser_getText in lines 7 and 10, because the loop executes twice, once for the ipaddress and once for the domain. When the current token holds the ipaddress , it has no data for the domain and vise versa. In effect, Listing 7 uses a common programming technique to "select" the appropriate element.

But what if we needed something more precise than testing for the Null value? The Null return value indicates only that a request for data failed to yield results. It doesn't indicate whether the failure occurred because the token did not contain the element or whether it held the element but the element did not have any data. In Listing 6 we are looking for data held by ipaddress, but the Null return value does not tell us whether the failure to locate this data occurs because there is no ipaddress element in the token or because it was found but was empty of data.

For this kind of precision we need a way of identifying the element which is being returned by XML_PullParser_getToken. XML_PullParser_isTypeOf is designed to identify the type of an element:

bool XML_PullParser_isTypeOf(string $name, array $el)

This function returns true if element $el is of type $name. Listing 8 rewrites Listing 7 using this function:

Listing 8

        1.   $child_tags = array();
        2.   $tags = array("ipaddress", "domain");
        3.   $parser = new XML_PullParser("DNS.xml",$tags,$child_tags);
        4.
        5.   while($token = $parser->XML_PullParser_getToken())
        6.   {
        7.      if ($parser->XML_PullParser_isTypeOf('ipaddress', $token)) {
        8.          echo "IP address: " . $parser->XML_PullParser_getText('ipaddress') ."\n";
        9.      }
       10.       else {
       11.          echo "Domain Name: " . $parser->XML_PullParser_getText('domain') ."\n";
       12.       }
       13.   }