eGroupWare 1.2.106-2 : Vue détaillée de XPath.class.php

Constructor

Resets the object so it's able to take a new xml sting/file

Constructing objects is slow. If you can, reuse ones that you have used already
by using this reset() function.

_bracketsCheck($term) X-Ref

This method checks the right amount and match of brackets

param: $term (string) String in which is checked.
return: (bool) TRUE: OK / FALSE: KO

_searchString($term, $expression) X-Ref

Looks for a string within another string -- BUT the search-string must be located *outside* of any brackets.

This method looks for a string within another string. Brackets in the
string the method is looking through will be respected, which means that
only if the string the method is looking for is located outside of
brackets, the search will be successful.

param: $term (string) String in which the search shall take place.
param: $expression (string) String that should be searched.
return: (int) This method returns -1 if no string was found,

_bracketExplode($separator, $term) X-Ref

Split a string by a searator-string -- BUT the separator-string must be located *outside* of any brackets.

Returns an array of strings, each of which is a substring of string formed
by splitting it on boundaries formed by the string separator.

param: $separator  (string) String that should be searched.
param: $term       (string) String in which the search shall take place.
return: (array)  see above

_getEndGroups($string, $open='[', $close=']') X-Ref

Split a string at it's groups, ie bracketed expressions

Returns an array of strings, when concatenated together would produce the original
string.  ie a(b)cde(f)(g) would map to:
array ('a', '(b)', cde', '(f)', '(g)')

param: $string  (string) The string to process
param: $open    (string) The substring for the open of a group
param: $close   (string) The substring for the close of a group
return: (array)  The parsed string, see above

_prestr(&$string, $delimiter, $offset=0) X-Ref

Retrieves a substring before a delimiter.

This method retrieves everything from a string before a given delimiter,
not including the delimiter.

param: $string (string) String, from which the substring should be extracted.
param: $delimiter (string) String containing the delimiter to use.
return: (string) Substring from the original string before the delimiter.

_afterstr($string, $delimiter, $offset=0) X-Ref

Retrieves a substring after a delimiter.

This method retrieves everything from a string after a given delimiter,
not including the delimiter.

param: $string (string) String, from which the substring should be extracted.
param: $delimiter (string) String containing the delimiter to use.
return: (string) Substring from the original string after the delimiter.

setVerbose($levelOfVerbosity = 1) X-Ref

Alter the verbose (error) level reporting.

Pass an int. >0 to turn on, 0 to turn off. The higher the number, the
higher the level of verbosity. By default, the class has a verbose level
of 1.

param: $levelOfVerbosity (int) default is 1 = on

getLastError() X-Ref

Returns the last occured error message.

return: string (may be empty if there was no error at all)

_setLastError($message='', $line='-', $file='-') X-Ref

Creates a textual error message and sets it.

example: 'XPath error in THIS_FILE_NAME:LINE. Message: YOUR_MESSAGE';

I don't think the message should include any markup because not everyone wants to debug
into the browser window.

You should call _displayError() rather than _setLastError() if you would like the message,
dependant on their verbose settings, echoed to the screen.

param: $message (string) a textual error message default is ''
param: $line (int) the line number where the error occured, use __LINE__

_displayError($message, $lineNumber='-', $file='-', $terminate=TRUE) X-Ref

Displays an error message.

This method displays an error messages depending on the users verbose settings
and sets the last error message.

If also possibly stops the execution of the script.
### Terminate should not be allowed --fab.  Should it??  N.S.

param: $message    (string)  Error message to be displayed.
param: $lineNumber (int)     line number given by __LINE__
param: $terminate  (bool)    (default TURE) End the execution of this script.

_displayMessage($message, $lineNumber='-', $file='-') X-Ref

Displays a diagnostic message

This method displays an error messages

param: $message (string) Error message to be displayed.
param: $lineNumber (int) line number given by __LINE__

_beginDebugFunction($functionName, $bDebugFlag) X-Ref

Called to begin the debug run of a function.

This method starts a <DIV><PRE> tag so that the entry to this function
is clear to the debugging user.  Call _closeDebugFunction() at the
end of the function to create a clean box round the function call.

author: Nigel Swinson <nigelswinson@users.sourceforge.net>
author: Sam   Blum    <bs_php@infeer.com>
param: $functionName (string) the name of the function we are beginning to debug
param: $bDebugFlag   (bool) TRUE if we are to draw a call stack, FALSE otherwise
return: (array)  the output from the microtime() function.

_closeDebugFunction($functionName, $returnValue = "", $bDebugFlag) X-Ref

Called to end the debug run of a function.

This method ends a <DIV><PRE> block and reports the time since $aStartTime
is clear to the debugging user.

author: Nigel Swinson <nigelswinson@users.sourceforge.net>
param: $functionName (string) the name of the function we are beginning to debug
param: $return_value (mixed) the return value from the function call that
param: $bDebugFlag (bool) TRUE if we are to draw a call stack, FALSE otherwise

_ProfBegin($sonFuncName) X-Ref

Profile begin call

_ProfEnd($sonFuncName) X-Ref

Profile end call

_ProfileToHtml() X-Ref

Show profile gathered so far as HTML table

_printContext($context) X-Ref

Echo an XPath context for diagnostic purposes

param: $context (array) An XPath context

_treeDump($node, $indent = '') X-Ref

This is a debug helper function. It dumps the node-tree as HTML

*QUICK AND DIRTY*. Needs some polishing.

param: $node (array) A node
param: $indent (string) (optional, default=''). For internal recursive calls.

Classe: XPathEngine - X-Ref

XPathEngine($userXmlOptions=array() X-Ref

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);

param: $userXmlOptions (array) (optional) Vector of (<optionID>=><value>,

reset() X-Ref

Resets the object so it's able to take a new xml sting/file

Constructing objects is slow. If you can, reuse ones that you have used already
by using this reset() function.

getProperties($param=NULL) X-Ref

Returns the property/ies you want.

if $param is not given, all properties will be returned in a hash.

param: $param (string) the property you want the value of, or NULL for all the properties
return: (mixed) string OR hash of all params, or NULL on an unknown parameter.

setXmlOption($optionID, $value) X-Ref

Set an xml_parser_set_option()

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

setXmlOptions($userXmlOptions=array() X-Ref

Sets a number of xml_parser_set_option()s

param: $userXmlOptions (array) An array of parser options.

setCaseFolding($onOff=TRUE) X-Ref

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.

param: $onOff (bool) (default TRUE)

setSkipWhiteSpaces($onOff=TRUE) X-Ref

Alternative way to control whether skip-white-spaces is enabled for this XML parser.

Short cut to setXmlOptions(XML_OPTION_SKIP_WHITE, TRUE/FALSE)

When it comes to XML, skip-white-spaces will trim the tag content.
An XML file with no whitespace will be faster to process, but will make
your data less human readable when you come to write it out.

Running with this option on will slow the class down, so if you want to
speed up your XML, then run it through once skipping white-spaces, then
write out the new version of your XML without whitespace, then use the
new XML file with skip whitespaces turned off.

param: $onOff (bool) (default TRUE)

getNode($absoluteXPath='') X-Ref

Get the node defined by the $absoluteXPath.

param: $absoluteXPath (string) (optional, default is 'super-root') xpath to the node.
return: (array) The node, or FALSE if the node wasn't found.

wholeText($absoluteXPath, $textPartNr=NULL) X-Ref

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.

param: $absoluteXPath  (string)  xpath to the node (See above).
param: $textPartNr     (int)     If referring to a node, specifies which text part
return: (&string) A *reference* to the text if the node that the other

_stringValue($node) X-Ref

Obtain the string value of an object

http://www.w3.org/TR/xpath#dt-string-value

"For every type of node, there is a way of determining a string-value for a node of that type.
For some types of node, the string-value is part of the node; for other types of node, the
string-value is computed from the string-value of descendant nodes."

param: $node (node) The node we have to convert
return: (string) The string value of the node. "" if the object has no evaluatable

exportAsHtml($absoluteXPath='', $hilightXpathList=array() X-Ref

Returns the containing XML as marked up HTML with specified nodes hi-lighted

param: $absoluteXPath    (string) The address of the node you would like to export.
param: $hilighXpathList  (array)  A list of nodes that you would like to highlight
return: (mixed)  The Xml document marked up as HTML so that it can

exportAsXml($absoluteXPath='', $xmlHeader=NULL) X-Ref

Given a context this function returns the containing XML

param: $absoluteXPath  (string) The address of the node you would like to export.
param: $xmlHeader      (array)  The string that you would like to appear before
return: (mixed)  The Xml fragment/document, suitable for writing

exportToFile($fileName, $absoluteXPath='', $xmlHeader=NULL) X-Ref

Generates a XML string with the content of the current document and writes it to a file.

Per default includes a <?xml ...> tag at the start of the data too.

param: $fileName       (string)
param: $absoluteXPath  (string) The path to the parent node you want(see text above)
param: $xmlHeader      (array)  The string that you would like to appear before
return: (string) The returned string contains well-formed XML data

_export($absoluteXPath='', $xmlHeader=NULL, $hilightXpathList='') X-Ref

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.

param: $absoluteXPath (string) (optional, default is root) The node we choose as top-node
param: $xmlHeader     (string) (optional) content before <root/> (see text above)
param: $hilightXpath  (array)  (optional) a vector of xPaths to nodes we wat to
return: (mixed)  The xml string, or FALSE on error.

_InternalExport($node) X-Ref

Export the xml document starting at the named node.

param: $node (node) The node we have to start exporting from
return: (string) The string representation of the node.

importFromFile($fileName) X-Ref

Reads a file or URL and parses the XML data.

Parse the XML source and (upon success) store the information into an internal structure.

param: $fileName (string) Path and name (or URL) of the file to be read and parsed.
return: (bool) TRUE on success, FALSE on failure (check getLastError())

importFromString($xmlString, $absoluteParentPath = '') X-Ref

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.

param: $xmlString           (string) Name of the string to be read and parsed.
param: $absoluteParentPath  (string) Node to append data too (see above)
return: (bool)   TRUE on success, FALSE on failure

_handleStartElement($parser, $nodeName, $attributes) X-Ref

Handles opening XML tags while parsing.

While parsing a XML document for each opening tag this method is
called. It'll add the tag found to the tree of document nodes.

param: $parser     (int)    Handler for accessing the current XML parser.
param: $name       (string) Name of the opening tag found in the document.
param: $attributes (array)  Associative array containing a list of

_handleEndElement($parser, $name) X-Ref

Handles closing XML tags while parsing.

While parsing a XML document for each closing tag this method is called.

param: $parser (int) Handler for accessing the current XML parser.
param: $name (string) Name of the closing tag found in the document.

_handleCharacterData($parser, $text) X-Ref

Handles character data while parsing.

While parsing a XML document for each character data this method
is called. It'll add the character data to the document tree.

param: $parser (int) Handler for accessing the current XML parser.
param: $text (string) Character data found in the document.

_handleDefaultData($parser, $text) X-Ref

Default handler for the XML parser.

While parsing a XML document for string not caught by one of the other
handler functions, we end up here.

param: $parser (int) Handler for accessing the current XML parser.
param: $text (string) Character data found in the document.

_handlePI($parser, $target, $data) X-Ref

Handles processing instruction (PI)

A processing instruction has the following format:
<?  target data  ? > e.g.  <? dtd version="1.0" ? >

Currently I have no bether idea as to left it 'as is' and treat the PI data as normal
text (and adding the surrounding PI-tags <? ? >).

param: $parser (int)    Handler for accessing the current XML parser.
param: $target (string) Name of the PI target. E.g. XML, PHP, DTD, ...
param: $data   (string) Associative array containing a list of

_createSuperRoot() X-Ref

Creates a super root node.

_internalAppendChild($stackParentIndex, $nodeName) X-Ref

Adds a new node to the XML document tree during xml parsing.

This method adds a new node to the tree of nodes of the XML document
being handled by this class. The new node is created according to the
parameters passed to this method.  This method is a much watered down
version of appendChild(), used in parsing an xml file only.

It is assumed that adding starts with root and progresses through the
document in parse order.  New nodes must have a corresponding parent. And
once we have read the </> tag for the element we will never need to add
any more data to that node.  Otherwise the add will be ignored or fail.

The function is faciliated by a nodeStack, which is an array of nodes that
we have yet to close.

param: $stackParentIndex (int)    The index into the nodeStack[] of the parent
param: $nodeName         (string) Name of the new node. *READONLY*
return: (bool)   TRUE if we successfully added a new child to

reindexNodeTree() X-Ref

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: (bool) TRUE on success, FALSE otherwise.

_generate_ids() X-Ref

Create the ids that are accessable through the generate-id() function

_recursiveReindexNodeTree($absoluteParentPath) X-Ref

Here's where the work is done for reindexing (see reindexNodeTree)

param: $absoluteParentPath (string) the xPath to the parent node
return: (bool) TRUE on success, FALSE otherwise.

cloneNode($node, $recursive=FALSE) X-Ref

Clone a node and it's child nodes.

NOTE: If the node has children you *MUST* use the reference operator!
E.g. $clonedNode =& cloneNode($node);
Otherwise the children will not point back to the parent, they will point
back to your temporary variable instead.

param: $node (mixed) Either a node (hash array) or an abs. Xpath to a node in
return: (&array) A node and it's child nodes.

match($xPathQuery, $baseXPath='') X-Ref

Matches (evaluates) an XPath query

This method tries to evaluate an XPath query by parsing it. A XML source must
have been imported before this method is able to work.

param: $xPathQuery  (string) XPath query to be evaluated.
param: $baseXPath   (string) (default is super-root) XPath query to a single document node,
return: (mixed)  The result of the XPath expression.  Either:

evaluate($xPathQuery, $baseXPath='') X-Ref

Alias for the match function

_removeLiterals($xPathQuery) X-Ref

Parse out the literals of an XPath expression.

Instead of doing a full lexical parse, we parse out the literal strings, and then
Treat the sections of the string either as parts of XPath or literal strings.  So
this function replaces each literal it finds with a literal reference, and then inserts
the reference into an array of strings that we can access.  The literals can be accessed
later from the literals associative array.

Example:
XPathExpr = /AAA[@CCC = "hello"]/BBB[DDD = 'world']
=>  literals: array("hello", "world")
return value: /AAA[@CCC = $1]/BBB[DDD = $2]

Note: This does not interfere with the VariableReference syntactical element, as these
elements must not start with a number.

param: $xPathQuery  (string) XPath expression to be processed
return: (string) The XPath expression without the literals.

_asLiteral($string) X-Ref

Returns the given string as a literal reference.

param: $string (string) The string that we are processing
return: (mixed) The literal string. FALSE if the string isn't a literal reference.

_addLiteral($string) X-Ref

Adds a literal to our array of literals

In order to make sure we don't interpret literal strings as XPath expressions, we have to
encode literal strings so that we know that they are not XPaths.

param: $string (string) The literal string that we need to store for future access
return: (mixed) A reference string to this literal.

_GetOperator($xPathQuery) X-Ref

Look for operators in the expression

Parses through the given expression looking for operators.  If found returns
the operands and the operator in the resulting array.

param: $xPathQuery  (string) XPath query to be evaluated.
return: (array)  If an operator is found, it returns an array containing

_evaluatePrimaryExpr($xPathQuery, $context, &$result) X-Ref

Evaluates an XPath PrimaryExpr

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

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

param: $xPathQuery  (string)   XPath query to be evaluated.
param: $context     (array)    The context from which to evaluate
param: $results     (mixed)    If the expression could be parsed and evaluated as one of these
return: (string)    An empty string if the query was successfully parsed and

_evaluateExpr($xPathQuery, $context) X-Ref

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) |

param: $xPathQuery  (string)   XPath query to be evaluated.
param: $context     (array)    An associative array the describes the context from which
return: (mixed)    The result of the XPath expression.  Either:

_evaluateOperator($left, $operator, $right, $operatorType, $context) X-Ref

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.

param: $left          (mixed)   The left operand
param: $right         (mixed)   The right operand
param: $operator      (string)  The operator to use to combine the operands
param: $operatorType  (string)  The type of the operator.  Either 'Boolean',
param: $context     (array)    The context from which to evaluate
return: (mixed)    The result of the XPath expression.  Either:

_evaluatePathExpr($PathExpr, $context) X-Ref

Evaluates an XPath PathExpr

It handles the following syntax:

http://www.w3.org/TR/xpath#node-sets
http://www.w3.org/TR/xpath#NT-LocationPath
http://www.w3.org/TR/xpath#path-abbrev
http://www.w3.org/TR/xpath#NT-Step

[19]   PathExpr              ::= LocationPath
| FilterExpr
| FilterExpr '/' RelativeLocationPath
| FilterExpr '//' RelativeLocationPath
[20]   FilterExpr            ::= PrimaryExpr
| FilterExpr Predicate
[1]    LocationPath          ::= RelativeLocationPath
| AbsoluteLocationPath
[2]    AbsoluteLocationPath  ::= '/' RelativeLocationPath?
| AbbreviatedAbsoluteLocationPath
[3]    RelativeLocationPath  ::= Step
| RelativeLocationPath '/' Step
| AbbreviatedRelativeLocationPath
[4]    Step                  ::= AxisSpecifier NodeTest Predicate*
| AbbreviatedStep
[5]    AxisSpecifier         ::= AxisName '::'
| AbbreviatedAxisSpecifier
[10]   AbbreviatedAbsoluteLocationPath
::= '//' RelativeLocationPath
[11]   AbbreviatedRelativeLocationPath
::= RelativeLocationPath '//' Step
[12]   AbbreviatedStep       ::= '.'
| '..'
[13]   AbbreviatedAxisSpecifier
::= '@'?

If you expand all the abbreviated versions, then the grammer simplifies to:

[19]   PathExpr              ::= RelativeLocationPath
| '/' RelativeLocationPath?
| FilterExpr
| FilterExpr '/' RelativeLocationPath
[20]   FilterExpr            ::= PrimaryExpr
| FilterExpr Predicate
[3]    RelativeLocationPath  ::= Step
| RelativeLocationPath '/' Step
[4]    Step                  ::= AxisName '::' NodeTest Predicate*

Conceptually you can say that we should split by '/' and try to treat the parts
as steps, and if that fails then try to treat it as a PrimaryExpr.

param: $PathExpr   (string) PathExpr syntactical element
param: $context    (array)  The context from which to evaluate
return: (mixed)  The result of the XPath expression.  Either:

_sortByDocOrder($xPathSet) X-Ref

Sort an xPathSet by doc order.

param: $xPathSet (array) Array of full paths to nodes that need to be sorted
return: (array) Array containing the same contents as $xPathSet, but

_evaluateStep($steps, $context) X-Ref

Evaluate a step from a XPathQuery expression at a specific contextPath.

Steps are the arguments of a XPathQuery when divided by a '/'. A contextPath is a
absolute XPath (or vector of XPaths) to a starting node(s) from which the step should
be evaluated.

param: $steps (array) Vector containing the remaining steps of the current
param: $context (array) The context from which to evaluate
return: (array) Vector of absolute XPath's as a result of the step

_checkPredicates($xPathSet, $predicates) X-Ref

Checks whether a node matches predicates.

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

param: $xPathSet   (array)  Array of full paths of all nodes to be tested.
param: $predicates (array)  Array of predicates to use.
return: (array)  Vector of absolute XPath's that match the given predicates.

_evaluateFunction($function, $arguments, $context) X-Ref

Evaluates an XPath function

This method evaluates a given XPath function with its arguments on a
specific node of the document.

param: $function      (string) Name of the function to be evaluated.
param: $arguments     (string) String containing the arguments being
param: $context       (array)  The context from which to evaluate
return: (mixed)  This method returns the result of the evaluation of

_checkNodeTest($contextPath, $nodeTest) X-Ref

Checks whether a node matches a node-test.

This method checks whether a node in the document matches a given node-test.
A node test is something like text(), node(), or an element name.

param: $contextPath (string) Full xpath of the node, which should be tested for
param: $nodeTest (string) String containing the node-test for the node.
return: (boolean) This method returns TRUE if the node matches the

_getAxis($step) X-Ref

Retrieves axis information from an XPath query step.

This method tries to extract the name of the axis and its node-test
from a given step of an XPath query at a given node.  If it can't parse
the step, then we treat it as a PrimaryExpr.

[4]    Step            ::= AxisSpecifier NodeTest Predicate*
| AbbreviatedStep
[5]    AxisSpecifier   ::= AxisName '::'
| AbbreviatedAxisSpecifier
[12]   AbbreviatedStep ::= '.'
| '..'
[13]   AbbreviatedAxisSpecifier
::=    '@'?

[7]    NodeTest        ::= NameTest
| NodeType '(' ')'
| 'processing-instruction' '(' Literal ')'
[37]   NameTest        ::= '*'
| NCName ':' '*'
| QName
[38]   NodeType        ::= 'comment'
| 'text'
| 'processing-instruction'
| 'node'

param: $step     (string) String containing a step of an XPath query.
return: (array)  Contains information about the axis found in the step, or FALSE

_handleAxis_child($axis, $contextPath) X-Ref

Handles the XPath child axis.

This method handles the XPath child axis.  It essentially filters out the
children to match the name specified after the '/'.

param: $axis        (array)  Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should
return: (array)  A vector containing all nodes that were found, during

_handleAxis_parent($axis, $contextPath) X-Ref

Handles the XPath parent axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the

_handleAxis_attribute($axis, $contextPath) X-Ref

Handles the XPath attribute axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_self($axis, $contextPath) X-Ref

Handles the XPath self axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_descendant($axis, $contextPath) X-Ref

Handles the XPath descendant axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_ancestor($axis, $contextPath) X-Ref

Handles the XPath ancestor axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_namespace($axis, $contextPath) X-Ref

Handles the XPath namespace axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_following($axis, $contextPath) X-Ref

Handles the XPath following axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_preceding($axis, $contextPath) X-Ref

Handles the XPath preceding axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_following_sibling($axis, $contextPath) X-Ref

Handles the XPath following-sibling axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_preceding_sibling($axis, $contextPath) X-Ref

Handles the XPath preceding-sibling axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_descendant_or_self($axis, $contextPath) X-Ref

Handles the XPath descendant-or-self axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleAxis_ancestor_or_self( $axis, $contextPath) X-Ref

Handles the XPath ancestor-or-self axis.

This method handles the XPath ancestor-or-self axis.

param: $axis (array) Array containing information about the axis.
param: $contextPath (string) xpath to starting node from which the axis should be processed.
return: (array) A vector containing all nodes that were found, during the evaluation of the axis.

_handleFunction_last($arguments, $context) X-Ref

Handles the XPath function last.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_position($arguments, $context) X-Ref

Handles the XPath function position.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_count($arguments, $context) X-Ref

Handles the XPath function count.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_id($arguments, $context) X-Ref

Handles the XPath function id.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_name($arguments, $context) X-Ref

Handles the XPath function name.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_string($arguments, $context) X-Ref

Handles the XPath function string.

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

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_concat($arguments, $context) X-Ref

Handles the XPath function concat.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_starts_with($arguments, $context) X-Ref

Handles the XPath function starts-with.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_contains($arguments, $context) X-Ref

Handles the XPath function contains.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_substring_before($arguments, $context) X-Ref

Handles the XPath function substring-before.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_substring_after($arguments, $context) X-Ref

Handles the XPath function substring-after.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_substring($arguments, $context) X-Ref

Handles the XPath function substring.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_string_length($arguments, $context) X-Ref

Handles the XPath function string-length.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_normalize_space($arguments, $context) X-Ref

Handles the XPath function normalize-space.

The normalize-space function returns the argument string with whitespace
normalized by stripping leading and trailing whitespace and replacing sequences
of whitespace characters by a single space.
If the argument is omitted, it defaults to the context node converted to a string,
in other words the string-value of the context node

param: $arguments (string) String containing the arguments that were passed to the function.
param: $context (array) The context from which to evaluate the function
return: (stri)g trimed string

_handleFunction_translate($arguments, $context) X-Ref

Handles the XPath function translate.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_boolean($arguments, $context) X-Ref

Handles the XPath function boolean.

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

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_not($arguments, $context) X-Ref

Handles the XPath function not.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_true($arguments, $context) X-Ref

Handles the XPath function TRUE.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_false($arguments, $context) X-Ref

Handles the XPath function FALSE.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_lang($arguments, $context) X-Ref

Handles the XPath function lang.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_number($arguments, $context) X-Ref

Handles the XPath function number.

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

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_sum($arguments, $context) X-Ref

Handles the XPath function sum.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_floor($arguments, $context) X-Ref

Handles the XPath function floor.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_ceiling($arguments, $context) X-Ref

Handles the XPath function ceiling.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_round($arguments, $context) X-Ref

Handles the XPath function round.

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_x_lower($arguments, $context) X-Ref

Handles the XPath function x-lower.

lower case a string.
string x-lower(string)

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_x_upper($arguments, $context) X-Ref

Handles the XPath function x-upper.

upper case a string.
string x-upper(string)

param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

_handleFunction_generate_id($arguments, $context) X-Ref

Handles the XPath function generate-id.

Produce a unique id for the first node of the node set.

Example usage, produces an index of all the nodes in an .xml document, where the content of each
"section" is the exported node as XML.

$aFunctions = $xPath->match('//');

foreach ($aFunctions as $Function) {
$id = $xPath->match("generate-id($Function)");
echo "<a href='#$id'>$Function</a><br>";
}

foreach ($aFunctions as $Function) {
$id = $xPath->match("generate-id($Function)");
echo "<h2 id='$id'>$Function</h2>";
echo htmlspecialchars($xPath->exportAsXml($Function));
}

author: Ricardo Garcia
param: $arguments     (string) String containing the arguments that were passed to the function.
param: $context       (array)  The context from which to evaluate the function
return: (mixed)  Depending on the type of function being processed

decodeEntities($encodedData, $reverse=FALSE) X-Ref

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.

param: $encodedData (mixed) The string or array that has entities you would like to remove
param: $reverse     (bool)  If TRUE entities will be encoded rather than decoded, ie
return: (mixed) The string or array returned with entities decoded.

equalNodes($node1, $node2) X-Ref

Compare two nodes to see if they are equal (point to the same node in the doc)

2 nodes are considered equal if the absolute XPath is equal.

param: $node1 (mixed) Either an absolute XPath to an node OR a real tree-node (hash-array)
param: $node2 (mixed) Either an absolute XPath to an node OR a real tree-node (hash-array)
return: (bool) TRUE if equal (see text above), FALSE if not (and on error).

getNodePath($node) X-Ref

Get the absolute XPath of a node that is in a document tree.

param: $node (array) A real tree-node (hash-array)
return: (string) The string path to the node or FALSE on error.

getParentXPath($absoluteXPath) X-Ref

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

param: $childPath (string) String containing an absolute XPath query
return: (string) returns the absolute XPath of the parent

hasChildNodes($absoluteXPath) X-Ref

Returns TRUE if the given node has child nodes below it

param: $absoluteXPath (string) full path of the potential parent node
return: (bool) TRUE if this node exists and has a child, FALSE otherwise

_translateAmpersand($xmlSource, $reverse=FALSE) X-Ref

Translate all ampersands to it's literal entities '&' and back.

I wasn't aware of this problem at first but it's important to understand why we do this.
At first you must know:
a) PHP's XML parser *translates* all entities to the equivalent char E.g. < is returned as '<'
b) PHP's XML parser (in V 4.1.0) has problems with most *literal* entities! The only one's that are
recognized are &, < > and ". *ALL* others (like   © a.s.o.) cause an
XML_ERROR_UNDEFINED_ENTITY error. I reported this as bug at http://bugs.php.net/bug.php?id=15092
(It turned out not to be a 'real' bug, but one of those nice W3C-spec things).

Forget position b) now. It's just for info. Because the way we will solve a) will also solve b) too.

THE PROBLEM
To understand the problem, here a sample:
Given is the following XML:    "<AAA> <   > </AAA>"
Try to parse it and PHP's XML parser will fail with a XML_ERROR_UNDEFINED_ENTITY becaus of
the unknown litteral-entity ' '. (The numeric equivalent ' ' would work though).
Next try is to use the numeric equivalent 160 for ' ', thus  "<AAA> <   > </AAA>"
The data we receive in the tag <AAA> is  " <   > ". So we get the *translated entities* and
NOT the 3 entities <   &gt. Thus, we will not even notice that there were entities at all!
In *most* cases we're not able to tell if the data was given as entity or as 'normal' char.
E.g. When receiving a quote or a single space were not able to tell if it was given as 'normal' char
or as   or ". Thus we loose the entity-information of the XML-data!

THE SOLUTION
The better solution is to keep the data 'as is' by replacing the '&' before parsing begins.
E.g. Taking the original input from above, this would result in "<AAA> &lt; &nbsp; &gt; </AAA>"
The data we receive now for the tag <AAA> is  " <   > ". and that's what we want.

The bad thing is, that a global replace will also replace data in section that are NOT translated by the
PHP XML-parser. That is comments (), IP-sections (stuff between <? ? >) and CDATA-block too.
So all data comming from those sections must be reversed. This is done during the XML parse phase.
So:
a) Replacement of all '&' in the XML-source.
b) All data that is not char-data or in CDATA-block have to be reversed during the XML-parse phase.

param: $xmlSource (string) The XML string
return: (string) The XML string with translated ampersands.

Classe: XPath - X-Ref

XPath($fileName='', $userXmlOptions=array() X-Ref

Constructor of the class

Optionally you may call this constructor with the XML-filename to parse and the
XML option vector. A option vector sample:
$xmlOpt = array(XML_OPTION_CASE_FOLDING => FALSE, XML_OPTION_SKIP_WHITE => TRUE);

param: $userXmlOptions (array) (optional) Vector of (<optionID>=><value>, <optionID>=><value>, ...)
param: $fileName (string) (optional) Filename of XML file to load from.

reset() X-Ref

Resets the object so it's able to take a new xml sting/file

Constructing objects is slow. If you can, reuse ones that you have used already
by using this reset() function.

setModMatch($modMatch = XPATH_QUERYHIT_ALL) X-Ref

Resolves and xPathQuery array depending on the property['modMatch']

Most of the modification functions of XPath will also accept a xPathQuery (instead
of an absolute Xpath). The only problem is that the query could match more the one
node. The question is, if the none, the fist or all nodes are to be modified.
The behaver can be set with setModMatch()

param: $modMatch (int) One of the following:

nodeName($xPathQuery) X-Ref

Retrieves the name(s) of a node or a group of document nodes.

This method retrieves the names of a group of document nodes
specified in the argument. So if the argument was '/A[1]/B[2]' then it
would return 'B' if the node did exist in the tree.

param: $xPathQuery (mixed) Array or single full document path(s) of the node(s),
return: (mixed) Array or single string of the names of the specified

removeChild($xPathQuery, $autoReindex=TRUE) X-Ref

Removes a node from the XML document.

This method removes a node from the tree of nodes of the XML document. If the node
is a document node, all children of the node and its character data will be removed.
If the node is an attribute node, only this attribute will be removed, the node to which
the attribute belongs as well as its children will remain unmodified.

NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery  (string) xpath to the node (See note above).
param: $autoReindex (bool)   (optional, default=TRUE) Reindex the document to reflect
return: (bool)   TRUE on success, FALSE on error;

replaceChildByData($xPathQuery, $data, $autoReindex=TRUE) X-Ref

Replace a node with any data string. The $data is taken 1:1.

This function will delete the node you define by $absoluteXPath (plus it's sub-nodes) and
substitute it by the string $text. Often used to push in not well formed HTML.
WARNING:
The $data is taken 1:1.
You are in charge that the data you enter is valid XML if you intend
to export and import the content again.

NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery  (string) xpath to the node (See note above).
param: $data        (string) String containing the content to be set. *READONLY*
param: $autoReindex (bool)   (optional, default=TRUE) Reindex the document to reflect
return: (bool)   TRUE on success, FALSE on error;

replaceChild($xPathQuery, $node, $autoReindex=TRUE) X-Ref

Replace the node(s) that matches the xQuery with the passed node (or passed node-tree)

If the passed node is a string it's assumed to be XML and replaceChildByXml()
will be called.
NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery  (string) Xpath to the node being replaced.
param: $node        (mixed)  String or Array (Usually a String)
param: $autoReindex (bool)   (optional, default=TRUE) Reindex the document to reflect
return: (array)  The last replaced $node (can be a whole sub-tree)

insertChild($xPathQuery, $node, $shiftRight=TRUE, $afterText=TRUE, $autoReindex=TRUE) X-Ref

Insert passed node (or passed node-tree) at the node(s) that matches the xQuery.

With parameters you can define if the 'hit'-node is shifted to the right or left
and if it's placed before of after the text-part.
Per derfault the 'hit'-node is shifted to the right and the node takes the place
the of the 'hit'-node.
NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

E.g. Following is given:           AAA[1]
/       \
..BBB[1]..BBB[2] ..

a) insertChild('/AAA[1]/BBB[2]', <node CCC>)
b) insertChild('/AAA[1]/BBB[2]', <node CCC>, $shiftRight=FALSE)
c) insertChild('/AAA[1]/BBB[2]', <node CCC>, $shiftRight=FALSE, $afterText=FALSE)

a)                          b)                           c)
AAA[1]                       AAA[1]                       AAA[1]
/    |   \                   /    |   \                   /    |   \
..BBB[1]..CCC[1]BBB[2]..     ..BBB[1]..BBB[2]..CCC[1]     ..BBB[1]..BBB[2]CCC[1]..

#### Do a complete review of the "(optional)" tag after several arguments.

param: $xPathQuery  (string) Xpath to the node to append.
param: $node        (mixed)  String or Array (Usually a String)
param: $shiftRight  (bool)   (optional, default=TRUE) Shift the target node to the right.
param: $afterText   (bool)   (optional, default=TRUE) Insert after the text.
param: $autoReindex (bool)   (optional, default=TRUE) Reindex the document to reflect
return: (mixed)  FALSE on error (or no match). On success we return the path(s) to the newly

appendChild($xPathQuery, $node, $afterText=FALSE, $autoReindex=TRUE) X-Ref

Appends a child to anothers children.

If you intend to do a lot of appending, you should leave autoIndex as FALSE
and then call reindexNodeTree() when you are finished all the appending.

param: $xPathQuery  (string) Xpath to the node to append to.
param: $node        (mixed)  String or Array (Usually a String)
param: $afterText   (bool)   (optional, default=FALSE) Insert after the text.
param: $autoReindex (bool)   (optional, default=TRUE) Reindex the document to reflect
return: (mixed)  FALSE on error (or no match). On success we return the path(s) to the newly

insertBefore($xPathQuery, $node, $afterText=TRUE, $autoReindex=TRUE) X-Ref

Inserts a node before the reference node with the same parent.

If you intend to do a lot of appending, you should leave autoIndex as FALSE
and then call reindexNodeTree() when you are finished all the appending.

param: $xPathQuery  (string) Xpath to the node to insert new node before
param: $node        (mixed)  String or Array (Usually a String)
param: $afterText   (bool)   (optional, default=FLASE) Insert after the text.
param: $autoReindex (bool)   (optional, default=TRUE) Reindex the document to reflect
return: (mixed)  FALSE on error (or no match). On success we return the path(s) to the newly

getAttributes($absoluteXPath, $attrName=NULL) X-Ref

Retrieves a dedecated attribute value or a hash-array of all attributes of a node.

The first param $absoluteXPath must be a valid xpath OR a xpath-query that results
to *one* xpath. If the second param $attrName is not set, a hash-array of all attributes
of that node is returned.

Optionally you may pass an attrubute name in $attrName and the function will return the
string value of that attribute.

param: $absoluteXPath (string) Full xpath OR a xpath-query that results to *one* xpath.
param: $attrName (string) (Optional) The name of the attribute. See above.
return: (mixed) hash-array or a string of attributes depending if the

setAttribute($xPathQuery, $name, $value, $overwrite=TRUE) X-Ref

Set attributes of a node(s).

This method sets a number single attributes. An existing attribute is overwritten (default)
with the new value, but setting the last param to FALSE will prevent overwritten.
NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery (string) xpath to the node (See note above).
param: $name       (string) Attribute name.
param: $value      (string) Attribute value.
param: $overwrite  (bool)   If the attribute is already set we overwrite it (see text above)
return: (bool)   TRUE on success, FALSE on failure.

setAttributes($xPathQuery, $attributes, $overwrite=TRUE) X-Ref

Version of setAttribute() that sets multiple attributes to node(s).

This method sets a number of attributes. Existing attributes are overwritten (default)
with the new values, but setting the last param to FALSE will prevent overwritten.
NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery (string) xpath to the node (See note above).
param: $attributes (array)  associative array of attributes to set.
param: $overwrite  (bool)   If the attributes are already set we overwrite them (see text above)
return: (bool)   TRUE on success, FALSE otherwise

removeAttribute($xPathQuery, $attrList=NULL) X-Ref

Removes an attribute of a node(s).

This method removes *ALL* attributres per default unless the second parameter $attrList is set.
$attrList can be either a single attr-name as string OR a vector of attr-names as array.
E.g.
removeAttribute(<xPath>);                     # will remove *ALL* attributes.
removeAttribute(<xPath>, 'A');                # will only remove attributes called 'A'.
removeAttribute(<xPath>, array('A_1','A_2')); # will remove attribute 'A_1' and 'A_2'.
NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery (string) xpath to the node (See note above).
param: $attrList   (mixed)  (optional) if not set will delete *all* (see text above)
return: (bool)   TRUE on success, FALSE if the node couldn't be found

getData($xPathQuery) X-Ref

Retrieve all the text from a node as a single string.

Sample
Given is: <AA> This <BB\>is <BB\>  some<BB\>text </AA>
Return of getData('/AA[1]') would be:  " This is   sometext "
The first param $xPathQuery must be a valid xpath OR a xpath-query that
results to *one* xpath.

param: $xPathQuery (string) xpath to the node - resolves to *one* xpath.
return: (mixed)  The returned string (see above), FALSE if the node

getDataParts($xPathQuery) X-Ref

Retrieve all the text from a node as a vector of strings

Where each element of the array was interrupted by a non-text child element.

Sample
Given is: <AA> This <BB\>is <BB\>  some<BB\>text </AA>
Return of getDataParts('/AA[1]') would be:  array([0]=>' This ', [1]=>'is ', [2]=>'  some', [3]=>'text ');
The first param $absoluteXPath must be a valid xpath OR a xpath-query that results
to *one* xpath.

param: $xPathQuery (string) xpath to the node - resolves to *one* xpath.
return: (mixed)  The returned array (see above), or FALSE if node is not

substringData($absoluteXPath, $offset = 0, $count = NULL) X-Ref

Retrieves a sub string of a text-part OR attribute-value.

This method retrieves the sub string of a specific text-part OR (if the
$absoluteXPath references an attribute) the the sub string  of the attribute value.
If no 'direct referencing' is used (Xpath ends with text()[<part-number>]), then
the first text-part of the node ist returned (if exsiting).

param: $absoluteXPath (string) Xpath to the node (See note above).
param: $offset        (int)    (optional, default is 0) Starting offset. (Just like PHP's substr())
param: $count         (number) (optional, default is ALL) Character count  (Just like PHP's substr())
return: (mixed)  The sub string, FALSE if not found or on error

replaceData($xPathQuery, $replacement, $offset = 0, $count = 0, $textPartNr=1) X-Ref

Replace a sub string of a text-part OR attribute-value.

NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery    (string) xpath to the node (See note above).
param: $replacement   (string) The string to replace with.
param: $offset        (int)    (optional, default is 0) Starting offset. (Just like PHP's substr_replace ())
param: $count         (number) (optional, default is 0=ALL) Character count  (Just like PHP's substr_replace())
param: $textPartNr    (int)    (optional) (see _getTextSet() )
return: (bool)   The new string value on success, FALSE if not found or on error

insertData($xPathQuery, $data, $offset=0) X-Ref

Insert a sub string in a text-part OR attribute-value.

NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery (string) xpath to the node (See note above).
param: $data       (string) The string to replace with.
param: $offset     (int)    (optional, default is 0) Offset at which to insert the data.
return: (bool)   The new string on success, FALSE if not found or on error

appendData($xPathQuery, $data, $textPartNr=1) X-Ref

Append text data to the end of the text for an attribute OR node text-part.

This method adds content to a node. If it's an attribute node, then
the value of the attribute will be set, otherwise the passed data will append to
character data of the node text-part. Per default the first text-part is taken.

NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery (string) to the node(s) (See note above).
param: $data       (string) String containing the content to be added.
param: $textPartNr (int)    (optional, default is 1) (see _getTextSet())
return: (bool)   TRUE on success, otherwise FALSE

deleteData($xPathQuery, $offset=0, $count=0, $textPartNr=1) X-Ref

Delete the data of a node.

This method deletes content of a node. If it's an attribute node, then
the value of the attribute will be removed, otherwise the node text-part.
will be deleted.  Per default the first text-part is deleted.

NOTE: When passing a xpath-query instead of an abs. Xpath.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery (string) to the node(s) (See note above).
param: $offset     (int)    (optional, default is 0) Starting offset. (Just like PHP's substr_replace())
param: $count      (number) (optional, default is 0=ALL) Character count.  (Just like PHP's substr_replace())
param: $textPartNr (int)    (optional, default is 0) the text part to delete (see _getTextSet())
return: (bool)   TRUE on success, otherwise FALSE

_xml2Document($xmlString) X-Ref

Parse the XML to a node-tree. A so called 'document'

param: $xmlString (string) The string to turn into a document node.
return: (&array) a node-tree

_getTextSet($xPathQuery, $textPartNr=1) X-Ref

Get a reference-list to node text part(s) or node attribute(s).

If the Xquery references an attribute(s) (Xquery ends with attribute::),
then the text value of the node-attribute(s) is/are returned.
Otherwise the Xquery is referencing to text part(s) of node(s). This can be either a
direct reference to text part(s) (Xquery ends with text()[<nr>]) or indirect reference
(a simple Xquery to node(s)).
1) Direct Reference (Xquery 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  Xquery to node(s)):
Default is to return the first text part(s). 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 vector is a set of references to the text parts / attributes.
This is handy, if you wish to modify the contents.
NOTE II: text-part numbers out of range will not be in the list
NOTE III:Instead of an absolute xpath you may also pass a xpath-query.
Depending on setModMatch() one, none or multiple nodes are affected.

param: $xPathQuery (string) xpath to the node (See note above).
param: $textPartNr (int)    String containing the content to be set.
return: (mixed)  A vector of *references* to the text that match, or

_resolveXPathQueryForNodeMod($xPathQuery, $functionName) X-Ref

Resolves an xPathQuery vector for a node op for modification

It is possible to create a brand new object, and try to append and insert nodes
into it, so this is a version of _resolveXPathQuery() that will autocreate the
super root if it detects that it is not present and the $xPathQuery is empty.

Also it demands that there be at least one node returned, and displays a suitable
error message if the returned xPathSet does not contain any nodes.

param: $xPathQuery (string) An xpath query targeting a single node.  If empty()
param: $function   (string) The function in which this check was called
return: (array)  Vector of $absoluteXPath's (May be empty)

_resolveXPathQuery($xPathQuery, $function) X-Ref

Resolves an xPathQuery vector depending on the property['modMatch']

To:
- all matches,
- the first
- none (If the query matches more then one node.)
see  setModMatch() for details

param: $xPathQuery (string) An xpath query targeting a single node.  If empty()
param: $function   (string) The function in which this check was called
return: (array)  Vector of $absoluteXPath's (May be empty)

_title($title) X-Ref

Produces a short title line.

Author:	S.Blum / N.Swinson / D.Allen / (P.Mehl)
Version:	3.5
Poids:	6355 lignes (273 kb)
Inclus ou requis:	2 fois
Référencé:	0 fois
Nécessite:	0 fichiers

Code source de eGroupWare 1.2.106-2

/phpsysinfo/includes/ -> XPath.class.php (sommaire)

Définit 3 classes