• var:

  An array of child elements of interest, which is used by the constructor.

  It can be passed into the constructor as an array of names or set using XML_PullParser_declareChildElements

• see: XML_PullParser_declareChildElements()

• var: (internal) the default token for various data accessors, generally consisting of elements declared in the $child_tags array. It is created by XML_PullParser_getElement

• var: internal

• var: internal

• var: the data stream

• var: internal

• var: holds the current namespace definition will be a string if only one namespace is declared, an array if more than one

• var: pointer into the attribute loop
• see: XML_PullParser::XML_PullParser_resetAttrLoopPtr()
• see: XML_PullParser::XML_PullParser_nextAttr()
• see: XML_PullParser::XML_PullParser_setAttrLoop()

used by methods which silently reset the $current_element

to an alternate token

• string $file: path/to/xml-file
• array $tags: array of elements on which to report back via tokens
• array $child_tags: array of child elements on which to report

Clear the escaped token stack

• see: XML_PullParser::XML_PullParser_getEscapedToken()

Removes all blank CDATA array elements from $token

Tests all CDATA packets against the PERL regex '/\w/' and deletes from the token array any CDATA element which does not meet this test.

• $token

Returns an associative array of attribute-name/attribute-value pairs found in the specified element.

Example:

  Array
  (
      [IP2] => 192.168.0.1
      [TECH] => tech@example.net
      [IP3] => 192.168.0.2
      [IP4] => 192.168.0.3
  )

When namespace support is not in effect, it is possible to extract individual names/values from members of this array, using the standard PHP constructs, each and </b>foreach</b>; or, where $name is known, it is possible to get the value: $value = $array[$name]. It is safest to use XML_PullParser_getAttrVal, which guarantees the current case folding setting.

When namespace support is invoked, XML_PullParser_getAttrVal should always be used, because attribute names are re-formatted into keys with the namespace URI's.

• return: Returns an associative array of name/value pairs where the keys are the attribute names. If $which is an integer, the result is from the $which_th instance of the element $el. If $which is set to false then it returns all the attributes found in $el and its child elements. In the latter case, if more than one attribute has the same name, there will be duplicate keys and only the last of the duplicates is returned because of the nature of associative arrays. Returns Null if no attributes are found. See XML_PullParser_getAttrValues for a function which guarantees duplicate names.

• mixed $name: name of the element to be searched, can be the name of $el itself. $name can also be an array returned from one of the tokenizing functions. e.g. XML_PullParser_getElement, XML_PullParser_getChild, XML_PullParser_getToken. In this case, the tokenized array will be used for $el and the name of its topmost element will be used for $name. This feature has particular functionality when used in a loop with XML_PullParser_nextElement, enabling the return value from XML_PullParser_nextElement to be passed into XML_PullParser_getAttributes as $name.
• mixed $which: (optional) integer or boolean. If $which is an integer, the function looks for the $which_th element of $name. If set to false, $name is ignored, and all attributes in $el are returned. But $name must still passed in as a Null parameter.
  NOTE: The false option is not suitable for cases where there is more than one attribute of the same name.
• array $el: (optional) the element where $name is found If $el is Null, the function first tries $current_element, then the current token. $el is ignored if $name is an array.

This method excavates all the attributes of a specified element.

It is guaranteed to return all attribute names and values even in cases where a parent has more than one child of the same name with same-named attributes. For instance:

       <directory>
           <file name = "tutorial.doc" role = "doc" />
           <file name = "classes.php" role = "php" />
           <file name = "constants.inc" role = "php" />
      </directory>

The above would return the following array:

	Array
	(
	    [0] => Array
	        (
	            [NAME] => tutorial.doc
	            [ROLE] => doc
	        )

	    [1] => Array
	        (
	            [NAME] => classes.php
	            [ROLE] => php
	        )

	    [2] => Array
	        (
	            [NAME] => constants.inc
	            [ROLE] => php
	        )

	)

• return: numerically indexed array of attribute-name/attribute-value pairs.
• see: XML_PullParser::XML_PullParser_setAttrLoop()

• array $ar: an associative array holding a single array element in which the key is the name of an xml child element enclosing any number of attributes and the value is either the name of the parent element (string) or a tokenized array which is the parent to $name. e.g.

   array($child=>$parent).

  $child and $parent can be the same.

Retrieves a child element and its dependents from its parent

This method extracts individual child elements from either $el or, if $el is not specified, from the $current_element or, failing that, from the current token.

$which specifies which instance of the child element to extract; the instances are treated as a sequence, in the order of appearance in the element's array, which follows the order of appearance in the XML document

if $child is the name of $el and $which == 1, then $el will be returned

• return: Returns child array if found, or Null if child not found in $el or False if $el was not passed in and no $current_element or current token is found.

• string $child: name of the element to be extracted
• integer $which: (optional) element to be extracted, defaults to 1,the first instance of the child
• array $el: (optional) element from which the child is to be extracted

Fetches children from parent using a string to specify the parent element.

See {@linkXML_PullParser_getChildren} for the method which fetches children from a parent specified as array

This method uses either $current_element or current token as the array from which to derive the child elements. If $current_element is not set then the current token is used.

• return: the named children of $el and all their dependents
• see: XML_PullParser::XML_PullParser_getChildren()

• string $name: name of the children sought
• string $el: name of the parent element where children reside

• return: $current_element

get the name of the element array $el or the element name portion of the internal string representation of the element

• mixed $el

This takes an associative array of XML element tags and HTML tags and converts it to an array structure suitable for use in XML_PullParser_getTextMarkedUp:

    array(xml_element =>html_tag_name, xml_element =>html_tag_name, . . )

For instance:

     array("code"=>"code", "emphasis"=>"b", "classname"=>"i");

• see: XML_PullParser::XML_PullParser_getStyledSpans()
• see: XML_PullParser::XML_PullParser_getCSSSpans()

• array $markup

Extracts the namespace URI from an internally constructed key for either attributes or elements

Element namespaces are held along with attributes in the attribute array assigned to an element:

  Array
  (
     [HTTP://EXAMPLE.COM/DNS.TXT/|IP] => 192.168.10.3
     [_ns_] => Array
        (
            [HTTP://EXAMPLE.COM/DNS.TXT/] => 1
        )
  )

These arrays are returned by XML_PullParser_getAttributes or can be extracted from the arrays returned by XML_PullParser_getAttrValues and XML_PullParser_nextAttr

1. If the parameter is a string, this method assumes that it is the internal name of an attribute, as in the example above: HTTP://EXAMPLE.COM/DNS.TXT/|IP
2. If the parameter is an array and $name is not specified, it assumes that the element's own namespace is being sought. This is held in '_ns_';
3. If the parameter is an array and $name is specified, it looks for the attribute of that $name.

• return: namespace URI or NULL if not found

• mixed $str: the internally constructed attribute name or an attribute array,
• string $name: optional name of the attribute; this is the unqualified name, i.e. without either the namespace URI or the namespace prefix

Adds attributes to spans and classes to spans and is used with XML_PullParser_getTextMarkedUp

This method takes two parameters, $attributes and $markup. Both are associative arrays. The $markup array is the same as the XML_PullParser_getCSSSpans array:

    array(xml_element =>css_class_name, xml_element =>css_class_name, . . )

    array(html_attribute =>attribute_value, . . )

If the first element in the $markup array has the following form:

  ("emphasis"=>"bold_text")

and if its counterpart in the $attributes array has this format:

  ("style"=>"font-size: 10pt")

The tag would become:

<span class="bold_text" style="font-size: 10pt">

The $markup array always defaults to

       class="markup"

The attribute/value pair of the $attributes array can be any valid markup.

The two arrays must be sequentially parallel, so that $markup-1 is modified by $attributes-1, etc. There cannot be duplicate keys, since the last duplicate overwrites the previous.

It returns an array dedicated for use in XML_PullParser_getTextMarkedUp; it can be combined with arrays returned by XML_PullParser_getStyledTags, XML_PullParser_getCSSSpans, and XML_PullParser_getHTMLTags.

• array $markup
• array $attributes

Get character data from the specified element.

If no parameters are passed to this method, it is assumed that the subject of the search defaults either to $current_element, or if that has not been set, then to the current token. All the character data of the of the default array is returned. This is in keeping with rule #1 below, where $which = 0 and $el is an array. (It is also implied by rule #5.)

1. If $el is an array and $which==0, the array is passed to XML_PullParser_getTextStripped and all character data enclosed by the parent START and END tags is returned;
   [A.] if the element has child elements with text, that text, too, will be returned.
   [B.] if there is more than one element of the same name bound into the array, all character data from all elements of the same name will be returned.
   
   
2. If $el is an array and $which > 0, the array is passed to XML_PullParser_getTextArray and the requested string is returned, using $which as an index into the array of strings returned by XML_PullParser_getTextArray. This array includes the text of parent and all descendents. To exclude descendents from this array set $xcl to true. Then the $which_th string will be selected only from elements named $el and not from any of its descendents.
   It is often advisable to call XML_PullParser_excludeBlanks in advance.
   
   
3. If $el is a string and the name of a child element, then either the $current_element, or if that's not set, the current token, is searched and the character data returned depends on the value of $which:
   [A.] if $which has a value > 0, then the character data from the $which_th instance of $el is returned but not the character data of its children;
   [B.] if $which retains its optional value of zero, then the character data of all elements named $el is returned but not the character data of their children
   
   
4. (Since release 1.2.1) If $el is a string and is the name of the default token, then the behavior is the same as when $el is an array.
   
   
5. If $el is Null, then the character data of the default token is returned, including that of child elements.
   
   
6. If $el is an array, or the name of the default token (see point 4 above), then the result can be filtered through XML_PullParser_Childxcl by setting $xcl to TRUE.
   
   
7. Returns NULL or an Empty String if text is not found in $el
   
   
8. Returns FALSE if $el does not resolve to an array and neither $current_element nor current token is found

All requests to this function are preprocessed here and ultimately passed on to XML_PullParser_getTextStripped, which means that its output is subject to the CDATA modifiers: XML_PullParser_excludeBlanks, XML_PullParser_trimCdata, and XML_PullParser_excludeBlanksStrict.

• mixed $el: optional name of element or a tokenized array
• integer $which: position of child element within the parent (default = 0)
• boolean $xcl: (default=false) when set to true the array $el or the default token is filtered through XML_PullParser_Childxcl()

This method will mark up text, essentially for redisplay as in HTML, using the $mark_up array for determining which XML elements are to be marked up and how they are to be marked up.

The $mark_up array should be created using the functions provided: XML_PullParser_getHTMLTags, XML_PullParser_getCSSSpans, XML_PullParser_getStyledSpans, and XML_PullParser_getStyledTags.

 $mark_up = $parser->XML_PullParser_getCSSSpans(
         array("code"=>"code", "emphasis"=>"emphasis")
     );
 $mark_up += $parser->XML_PullParser_getHTMLTags(array("classname"=>"b"));

 $text = $parser->XML_PullParser_getTextMarkedUp($mark_up);

NOTE: The tags marked up by this function cannot be empty, i.e. they must have both an open tag and a closing tag.

In other respects, this function works essentially the same as XML_PullParser_getTextStripped with one difference: it is not subject to the CDATA modifiers $XML_PullParser_XCLUDE_BLANKS, $XML_PullParser_XCLUDE_BLANKS_STRICT, $XML_PullParser_TRIM_CDATA

• array $mark_up
• mixed $el: see XML_PullParser_getTextStripped

XML_PullParser_getToken initializes and returns the next top level element and all of its children for use with the class data access methods. The top level elements are those delcared in the tags array: XML_PullParser::$tags.

This method is the workhorse of XML_PullParser. It is repeatedly called, most typically in a while loop, to fetch the next token off the token stack. Each token consists of an element declared in the tags array and all of its dependent child elements. The tags array is pre-declared in XML_PullParser_declareElements or passed in through the constructor.

The companion to this method is XML_PullParser_getElement, which returns elements declared in in the child tags array: XML_PullParser::$child_tags.

• return: an array consisting of the next element in the token stack and all of its dependent children.
• see: XML_PullParser_declareElements()

The PHP XML parser, by default, converts all tag names to upper case, called case-folding.

This method returns TRUE if case folding is in effect. To put case sensitivity into effect call package-level XML_PullParser_caseSensitive.

Determine whether element $el is an element of type $name

• array $el
• string $name

Designed to work in loops using the internal array created by XML_PullParser_getElement.

This function removes each next element from the next element stack, and returns it until the stack is exhausted. The stack is a copy of $current_element.

This is useful only where there is more than one instance of an element:

    
    
    172.20.19.6
    example.com
    example_1.com
    example_2.com
    example_3.com
    www.example.com
    
    

Used in this situation, XML_PullParser_nextElement() will return each next server element in document order, making it possible to get at the text and the attributes. Note: This method is not used for accessing child elements of the elements saved by XML_PullParser_getElement. For that we have to use XML_PullParser_getSequence() or XML_PullParser_getChild(), or else include the child elements in the child tags array

The array it returns is a tokenized array that can be passed to the class methods which accept them. By default, this array is filtered through XML_PullParser_childXCL, which means that all children of the parent element are removed. This guarantees that the result returned when requesting text and attributes is for the element named in the parameter to XML_PullParser_getElement. But this also means that it is not suitable for use in applications which need to slurp together text from parent and all its children, as in a marked-up paragraph, since all the mark-up would be deleted in favor of the parent element.

The default behavior can be turned off by passing in a False value as a parameter, in which case the results are not filtered through XML_PullParser_childXCL

The idiom for its use is:

   $parser->XML_PullParser_getElement('element_name');
    while($next = $parser->XML_PullParser_nextElement()) {
         $data = $parser->XML_PullParser_getText($next);
    }

• see: XML_PullParser::$_next_element_array

• boolean $xcl: defaults to True; False turns off filtering through XML_PullParser_childXCL

Resets attribute loop pointer back to zero, so that the attributes loop can be re-read, starting at the top

• see: XML_PullParser::$_attr_loop_pos
• see: XML_PullParser::XML_PullParser_nextAttr()
• see: XML_PullParser::XML_PullParser_setAttrLoop()

Creates an array of all attributes located in $el and its children.

Use XML_PullParser::XML_PullParser_nextAttr() to get the attributes.

For fuller description and example of use see XML_PullParser_nextAttr

• return: accessed through XML_PullParser_nextAttr
• see: XML_PullParser::XML_PullParser_setAttrLoop_elcd()
• see: XML_PullParser::$_attr_loop_array
• see: XML_PullParser::$_attr_loop_pos
• see: XML_PullParser::XML_PullParser_resetAttrLoopPtr()

• array $el: (optional) if $el is not set then it is assumed that subject of the request is the $current_element or, lacking that, the current token
• boolean $assignText: (internal)

XML_PullParser_setAttrLoop_elcd is a wrapper for XML_PullParser_setAttrLoop.

This method differs from XML_PullParser_setAttrLoop in that it captures the text associated with each element, in addition to the attribute and element name. For an illustration of the array structure that it creates see XML_PullParser_nextAttr.

Like XML_PullParser_setAttrLoop, this method uses XML_PullParser_nextAttr to loop through the attribute array. The difference is that in the array returned by XML_PullParser_nextAttr, the second array element holds the element's character data instead of the empty string. For details see XML_PullParser_nextAttr.

This is an improvement on the old code for this method, which is still available as XML_PullParser_setAttrLoop_cdata. XML_PullParser_setAttrLoop_cdata should be used only if incompatibilties between the current and the previous version of XML_PullParser_setAttrLoop_elcd arise. In that event, please notify the developer at Myron_Turner_(at)_Shaw_(dot)_ca.

• see: XML_PullParser::XML_PullParser_resetAttrLoopPtr()
• see: XML_PullParser::XML_PullParser_setAttrLoop()
• see: XML_PullParser::XML_PullParser_nextAttr()
• see: XML_PullParser::$current_element

• array $el: optional tokenized array

Sets the delimiter for XML_PullParser_getTextStripped and returns the old delimiter

• return: old $delimiter
• see: XML_PullParser::XML_PullParser_getTextStripped()

• string $delimiter

Unsets current element and returns its value;

• return: $current_element

• $token

Converts token returned by _getTokenRaw to a form compatible with the tokens returned by {@linkXML_PullParser_getElement}

This method is essentially internal and is called by XML_PullParser_getToken.

Unless the raw token is converted, the PullParser data accesors are not available: XML_PullParser_getAttributes, XML_PullParser_getText, XML_PullParser_getTextStripped, XML_PullParser_getChild, XML_PullParser_getChildren

• array $token

PHP XML Callback: Internal

• $parser
• $name

This is used to test whether an element or an attribute falls within the current namespace definition.

This is mainly for internal use, particularly insofar as it is applied to elements. But it can be used by the programmer to determine whether an attribute resides within the current namespace definition. This can be done first by extracting the namespace URI from the attribute's name, using XML_PullParser_getNS_URI, and then passing into _is_current_NS() the URI and the attribute's value as key=>value array:

     $name = XML_PullParser_getNS_URI($name);
     if(_is_current_NS(array($name=>$value)) ) {
     }

• array $ns_array: this is a single element array of the type key=>value, where the key is the name space string and the value either an attribute value or TRUE

Helper function to XML_PullParser_childXCL

• $temp
• $pos

Get next chunk of data from XML Parser: Internal

• XML_PullParser_doc::_readData() : Reads and parses the submitted document as a string