Constructor XPathEngine (line 950)

Constructor

Optionally you may call this constructor with the XML-filename to parse and the XML option vector. Each of the entries in the option vector will be passed to xml_parser_set_option().

A option vector sample: $xmlOpt = array(XML_OPTION_CASE_FOLDING => FALSE, XML_OPTION_SKIP_WHITE => TRUE);

• see: XPathEngine::importFromFile(), XPathEngine::importFromString(), XPathEngine::setXmlOptions()

• $userXmlOptions $userXmlOptions: (array) (optional) Vector of (<optionID>=><value>, <optionID>=><value>, ...). See PHP's xml_parser_set_option() docu for a list of possible options.

decodeEntities (line 5037)

Decodes the character set entities in the given string.

This function is given for convenience, as all text strings or attributes are going to come back to you with their entities still encoded. You can use this function to remove these entites.

It makes use of the get_html_translation_table(HTML_ENTITIES) php library call, so is limited in the same ways. At the time of writing this seemed be restricted to iso-8859-1

### Provide an option that will do this by default.

• return: The string or array returned with entities decoded.

• $encodedData $encodedData: (mixed) The string or array that has entities you would like to remove
• $reverse $reverse: (bool) If TRUE entities will be encoded rather than decoded, ie < to &lt; rather than &lt; to <.

evaluate (line 2432)

Alias for the match function

• see: XPathEngine::match()

• $xPathQuery
• $baseXPath

exportAsXml (line 1245)

Given a context this function returns the containing XML

• return: The Xml fragment/document, suitable for writing out to an .xml file or as part of a larger xml file, or FALSE on error.
• see: XPathEngine::_export()

• $absoluteXPath $absoluteXPath: (string) The address of the node you would like to export. If empty the whole document will be exported.
• $xmlHeader $xmlHeader: (array) The string that you would like to appear before the XML content. ie before the <root></root>. If you do not specify this argument, the xmlHeader that was found in the parsed xml file will be used instead.

getNode (line 1079)

Get the node defined by the $absoluteXPath.

• return: The node, or FALSE if the node wasn't found.

• $absoluteXPath $absoluteXPath: (string) (optional, default is 'super-root') xpath to the node.

getParentXPath (line 5116)

Retrieves the absolute parent XPath query.

The parents stored in the tree are only relative parents...but all the parent information is stored in the XPath query itself...so instead we use a function to extract the parent from the absolute Xpath query

• return: returns the absolute XPath of the parent

• $childPath $absoluteXPath: (string) String containing an absolute XPath query

hasChildNodes (line 5131)

Returns TRUE if the given node has child nodes below it

• return: TRUE if this node exists and has a child, FALSE otherwise

• $absoluteXPath $absoluteXPath: (string) full path of the potential parent node

importFromString (line 1724)

Reads a string and parses the XML data.

Parse the XML source and (upon success) store the information into an internal structure. If a parent xpath is given this means that XML data is to be *appended* to that parent.

### If a function uses setLastError(), then say in the function header that getLastError() is useful.

• return: TRUE on success, FALSE on failure (check getLastError())

• $xmlString $xmlString: (string) Name of the string to be read and parsed.
• $absoluteParentPath $absoluteParentPath: (string) Node to append data too (see above)

reindexNodeTree (line 2159)

Update nodeIndex and every node of the node-tree.

Call after you have finished any tree modifications other wise a match with an xPathQuery will produce wrong results. The $this->nodeIndex[] is recreated and every nodes optimization data is updated. The optimization data is all the data that is duplicate information, would just take longer to find. Child nodes with value NULL are removed from the tree.

By default the modification functions in this component will automatically re-index the nodes in the tree. Sometimes this is not the behaver you want. To surpress the reindex, set the functions $autoReindex to FALSE and call reindexNodeTree() at the end of your changes. This sometimes leads to better code (and less CPU overhead).

Sample: ======= Given the xml is <AAA><B/>.<B/>.<B/></AAA> | Goal is <AAA>.<B/>.</AAA> (Delete B[1] and B[3]) $xPathSet = $xPath->match('//B'); # Will result in array('/AAA[1]/B[1]', '/AAA[1]/B[2]', '/AAA[1]/B[3]'); Three ways to do it. 1) Top-Down (with auto reindexing) - Safe, Slow and you get easily mix up with the the changing node index removeChild('/AAA[1]/B[1]'); // B[1] removed, thus all B[n] become B[n-1] !! removeChild('/AAA[1]/B[2]'); // Now remove B[2] (That originaly was B[3]) 2) Bottom-Up (with auto reindexing) - Safe, Slow and the changing node index (caused by auto-reindex) can be ignored. for ($i=sizeOf($xPathSet)-1; $i>=0; $i--) { if ($i==1) continue; removeChild($xPathSet[$i]); } 3) // Top-down (with *NO* auto reindexing) - Fast, Safe as long as you call reindexNodeTree() foreach($xPathSet as $xPath) { // Specify no reindexing if ($xPath == $xPathSet[1]) continue; removeChild($xPath, $autoReindex=FALSE); // The object is now in a slightly inconsistent state. } // Finally do the reindex and the object is consistent again reindexNodeTree();

• return: TRUE on success, FALSE otherwise.
• see: XPathEngine::_recursiveReindexNodeTree()

setCaseFolding (line 1048)

Alternative way to control whether case-folding is enabled for this XML parser.

Short cut to setXmlOptions(XML_OPTION_CASE_FOLDING, TRUE/FALSE)

When it comes to XML, case-folding simply means uppercasing all tag- and attribute-names (NOT the content) if set to TRUE. Note if you have this option set, then your XPath queries will also be case folded for you.

• see: XML parser functions in PHP doc

• $onOff $onOff: (bool) (default TRUE)

setXmlOption (line 1017)

Set an xml_parser_set_option()

• see: XML parser functions in PHP doc

• $optionID $optionID: (int) The option ID (e.g. XML_OPTION_SKIP_WHITE)
• $value $value: (int) The option value.

wholeText (line 1115)

Get a the content of a node text part or node attribute.

If the absolute Xpath references an attribute (Xpath ends with @ or attribute::), then the text value of that node-attribute is returned. Otherwise the Xpath is referencing a text part of the node. This can be either a direct reference to a text part (Xpath ends with text()[<nr>]) or indirect reference (a simple abs. Xpath to a node). 1) Direct Reference (xpath ends with text()[<part-number>]): If the 'part-number' is omitted, the first text-part is assumed; starting by 1. Negative numbers are allowed, where -1 is the last text-part a.s.o. 2) Indirect Reference (a simple abs. Xpath to a node): Default is to return the *whole text*; that is the concated text-parts of the matching node. (NOTE that only in this case you'll only get a copy and changes to the returned value wounld have no effect). Optionally you may pass a parameter $textPartNr to define the text-part you want; starting by 1. Negative numbers are allowed, where -1 is the last text-part a.s.o.

NOTE I : The returned value can be fetched by reference E.g. $text =& wholeText(). If you wish to modify the text. NOTE II: text-part numbers out of range will return FALSE SIDENOTE:The function name is a suggestion from W3C in the XPath specification level 3.

• return: A *reference* to the text if the node that the other parameters describe or FALSE if the node is not found.

• $absoluteXPath $absoluteXPath: (string) xpath to the node (See above).
• $textPartNr $textPartNr: (int) If referring to a node, specifies which text part to query.

_asLiteral (line 2492)

Returns the given string as a literal reference.

• return: The literal string. FALSE if the string isn't a literal reference.

• $string $string: (string) The string that we are processing

_checkPredicates (line 3561)

Checks whether a node matches predicates.

This method checks whether a list of nodes passed to this method match a given list of predicates.

• return: Vector of absolute XPath's that match the given predicates.
• see: XPathEngine::_evaluateStep()

• $xPathSet $xPathSet: (array) Array of full paths of all nodes to be tested.
• $predicates $predicates: (array) Array of predicates to use.

_evaluateExpr (line 2858)

Evaluates an XPath Expr

$this->evaluate() is the entry point and does some inits, while this function is called recursive internaly for every sub-xPath expresion we find. It handles the following syntax, and calls evaluatePathExpr if it finds that none of this grammer applies.

http://www.w3.org/TR/xpath#section-Basics

[14] Expr ::= OrExpr [21] OrExpr ::= AndExpr | OrExpr 'or' AndExpr [22] AndExpr ::= EqualityExpr | AndExpr 'and' EqualityExpr [23] EqualityExpr ::= RelationalExpr | EqualityExpr '=' RelationalExpr | EqualityExpr '!=' RelationalExpr [24] RelationalExpr ::= AdditiveExpr | RelationalExpr '<' AdditiveExpr | RelationalExpr '>' AdditiveExpr | RelationalExpr '<=' AdditiveExpr | RelationalExpr '>=' AdditiveExpr [25] AdditiveExpr ::= MultiplicativeExpr | AdditiveExpr '+' MultiplicativeExpr | AdditiveExpr '-' MultiplicativeExpr [26] MultiplicativeExpr ::= UnaryExpr | MultiplicativeExpr MultiplyOperator UnaryExpr | MultiplicativeExpr 'div' UnaryExpr | MultiplicativeExpr 'mod' UnaryExpr [27] UnaryExpr ::= UnionExpr | '-' UnaryExpr [18] UnionExpr ::= PathExpr | UnionExpr '|' PathExpr

NOTE: The effect of the above grammar is that the order of precedence is (lowest precedence first): 1) or 2) and 3) =, != 4) <=, <, >=, > 5) +, - 6) *, div, mod 7) - (negate) 8) |

• return: The result of the XPath expression. Either: node-set (an ordered collection of nodes without duplicates) boolean (true or false) number (a floating-point number) string (a sequence of UCS characters)
• see: XPathEngine::evaluate()

• $xPathQuery $xPathQuery: (string) XPath query to be evaluated.
• $context $context: (array) An associative array the describes the context from which to evaluate the XPath Expr. Contains three members: 'nodePath' => The absolute XPath expression to the context node 'size' => The context size 'pos' => The context position

_evaluateOperator (line 3109)

Evaluate the result of an operator whose operands have been evaluated

If the operator type is not "NodeSet", then neither the left or right operators will be node sets, as the processing when one or other is an array is complex, and should be handled by the caller.

• return: The result of the XPath expression. Either: node-set (an ordered collection of nodes without duplicates) boolean (true or false) number (a floating-point number) string (a sequence of UCS characters)

• $left $left: (mixed) The left operand
• $right $operator: (mixed) The right operand
• $operator $right: (string) The operator to use to combine the operands
• $operatorType $operatorType: (string) The type of the operator. Either 'Boolean', 'Integer', 'String', or 'NodeSet'
• $context $context: (array) The context from which to evaluate

_evaluatePrimaryExpr (line 2697)

Evaluates an XPath PrimaryExpr

http://www.w3.org/TR/xpath#section-Basics

[15] PrimaryExpr ::= VariableReference | '(' Expr ')' | Literal | Number | FunctionCall

• return: An empty string if the query was successfully parsed and evaluated, else a string containing the reason for failing.
• see: XPathEngine::evaluate()

• $xPathQuery $xPathQuery: (string) XPath query to be evaluated.
• $context $context: (array) The context from which to evaluate
• $results &$result: (mixed) If the expression could be parsed and evaluated as one of these syntactical elements, then this will be either:
  • node-set (an ordered collection of nodes without duplicates)
  • boolean (true or false)
  • number (a floating-point number)
  • string (a sequence of UCS characters)

_export (line 1336)

Generates a XML string with the content of the current document.

This is the start for extracting the XML-data from the node-tree. We do some preperations and then call _InternalExport() to fetch the main XML-data. You optionally may pass xpath to any node that will then be used as top node, to extract XML-parts of the document. Default is '', meaning to extract the whole document.

You also may pass a 'xmlHeader' (usually something like <?xml version="1.0"? > that will overwrite any other 'xmlHeader', if there was one in the original source. If there wasn't one in the original source, and you still don't specify one, then it will use a default of <?xml version="1.0"? > Finaly, when exporting to HTML, you may pass a vector xPaths you want to hi-light. The hi-lighted tags and attributes will receive a nice color.

NOTE I : The output can have 2 formats: a) If "skip white spaces" is/was set. (Not Recommended - slower) The output is formatted by adding indenting and carriage returns. b) If "skip white spaces" is/was *NOT* set. 'as is'. No formatting is done. The output should the same as the the original parsed XML source.

• return: The xml string, or FALSE on error.

• $absoluteXPath $absoluteXPath: (string) (optional, default is root) The node we choose as top-node
• $xmlHeader $xmlHeader: (string) (optional) content before <root/> (see text above)
• $hilightXpath $hilightXpathList: (array) (optional) a vector of xPaths to nodes we wat to hi-light (see text above)