| packageless

# Procedural File: XPath.class.php Source Location: /lib/XPath/XPath.class.php ## Classes: ## Page Details: Php.XPath +======================================================================================================+ | A php class for searching an XML document using XPath, and making modifications using a DOM | style API. Does not require the DOM XML PHP library. | +======================================================================================================+ | What Is XPath: | -------------- | - "What SQL is for a relational database, XPath is for an XML document." -- Sam Blum | - "The primary purpose of XPath is to address parts of an XML document. In support of this | primary purpose, it also provides basic facilities for manipulting it." -- W3C | | XPath in action and a very nice intro is under: | http://www.zvon.org/xxl/XPathTutorial/General/examples.html | Specs Can be found under: | http://www.w3.org/TR/xpath W3C XPath Recommendation | http://www.w3.org/TR/xpath20 W3C XPath Recommendation | | NOTE: Most of the XPath-spec has been realized, but not all. Usually this should not be | problem as the missing part is either rarely used or it's simpler to do with PHP itself. +------------------------------------------------------------------------------------------------------+ | Requires PHP version 4.0.5 and up +------------------------------------------------------------------------------------------------------+ | Main Active Authors: | -------------------- | Nigel Swinson <nigelswinson@users.sourceforge.net> | Started around 2001-07, saved phpxml from near death and renamed to Php.XPath | Restructured XPath code to stay in line with XPath spec. | Sam Blum <bs_php@infeer.com> | Started around 2001-09 1st major restruct (V2.0) and testbench initiator. | 2nd (V3.0) major rewrite in 2002-02 | Daniel Allen <bigredlinux@yahoo.com> | Started around 2001-10 working to make Php.XPath adhere to specs | Main Former Author: Michael P. Mehl <mpm@phpxml.org> | Inital creator of V 1.0. Stoped activities around 2001-03 +------------------------------------------------------------------------------------------------------+ | Code Structure: | --------------_ | The class is split into 3 main objects. To keep usability easy all 3 | objects are in this file (but may be split in 3 file in future). | +-------------+ | | XPathBase | XPathBase holds general and debugging functions. | +------+------+ | v | +-------------+ XPathEngine is the implementation of the W3C XPath spec. It contains the | | XPathEngine | XML-import (parser), -export and can handle xPathQueries. It's a fully | +------+------+ functional class but has no functions to modify the XML-document (see following). | v | +-------------+ | | XPath | XPath extends the functionality with actions to modify the XML-document. | +-------------+ We tryed to implement a DOM - like interface. +------------------------------------------------------------------------------------------------------+ | Usage: | ------ | Scroll to the end of this php file and you will find a short sample code to get you started +------------------------------------------------------------------------------------------------------+ | Glossary: | --------- | To understand how to use the functions and to pass the right parameters, read following: | | Document: (full node tree, XML-tree) | After a XML-source has been imported and parsed, it's stored as a tree of nodes sometimes | refered to as 'document'. | | AbsoluteXPath: (xPath, xPathSet) | A absolute XPath is a string. It 'points' to *one* node in the XML-document. We use the | term 'absolute' to emphasise that it is not an xPath-query (see xPathQuery). A valid xPath | has the form like '/AAA[1]/BBB[2]/CCC[1]'. Usually functions that require a node (see Node) | will also accept an abs. XPath. | | Node: (node, nodeSet, node-tree) | Some funtions require or return a node (or a whole node-tree). Nodes are only used with the | XPath-interface and have an internal structure. Every node in a XML document has a unique | corresponding abs. xPath. That's why public functions that accept a node, will usually also | accept a abs. xPath (a string) 'pointing' to an existing node (see absolutXPath). | | XPathQuery: (xquery, query) | A xPath-query is a string that is matched against the XML-document. The result of the match | is a xPathSet (vector of xPath's). It's always possible to pass a single absoluteXPath | instead of a xPath-query. A valid xPathQuery could look like this: | '//XXX/*[contains(., "foo")]/..' (See the link in 'What Is XPath' to learn more). | | +------------------------------------------------------------------------------------------------------+ | Internals: | ---------- | - The Node Tree | ------------- | A central role of the package is how the XML-data is stored. The whole data is in a node-tree. | A node can be seen as the equvalent to a tag in the XML soure with some extra info. | For instance the following XML | <AAA foo="x">***<BBB/><CCC/>**<BBB/>*</AAA> | Would produce folowing node-tree: | 'super-root' <-- $nodeRoot (Very handy) | | | 'depth' 0 AAA[1] <-- top node. The 'textParts' of this node would be | / | \ 'textParts' => array('***','','**','*') | 'depth' 1 BBB[1] CCC[1] BBB[2] (NOTE: Is always size of child nodes+1) | - The Node | -------- | The node itself is an structure desiged mainly to be used in connection with the interface of PHP.XPath. | That means it's possible for functions to return a sub-node-tree that can be used as input of an other | PHP.XPath function. | | The main structure of a node is: | $node = array( | 'name' => '', # The tag name. E.g. In <FOO bar="aaa"/> it would be 'FOO' | 'attributes' => array(), # The attributes of the tag E.g. In <FOO bar="aaa"/> it would be array('bar'=>'aaa') | 'textParts' => array(), # Array of text parts surrounding the children E.g. <FOO>aa<A>bb<B/>cc</A>dd</FOO> -> array('aa','bb','cc','dd') | 'childNodes' => array(), # Array of refences (pointers) to child nodes. | | For optimisation reasions some additional data is stored in the node too: | 'parentNode' => NULL # Reference (pointer) to the parent node (or NULL if it's 'super root') | 'depth' => 0, # The tag depth (or tree level) starting with the root tag at 0. | 'pos' => 0, # Is the zero-based position this node has in the parent's 'childNodes'-list. | 'contextPos' => 1, # Is the one-based position this node has by counting the siblings tags (tags with same name) | 'xpath' => '' # Is the abs. XPath to this node. | | - The NodeIndex | ------------- | Every node in the tree has an absolute XPath. E.g '/AAA[1]/BBB[2]' the $nodeIndex is a hash array | to all the nodes in the node-tree. The key used is the absolute XPath (a string). | +------------------------------------------------------------------------------------------------------+ | License: | -------- | The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); | you may not use this file except in compliance with the License. You may obtain a copy of the | License at http://www.mozilla.org/MPL/ | | Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY | OF ANY KIND, either express or implied. See the License for the specific language governing | rights and limitations under the License. | | The Original Code is <phpXML/>. | | The Initial Developer of the Original Code is Michael P. Mehl. Portions created by Michael | P. Mehl are Copyright (C) 2001 Michael P. Mehl. All Rights Reserved. | | Contributor(s): N.Swinson / S.Blum / D.Allen | | Alternatively, the contents of this file may be used under the terms of either of the GNU | General Public License Version 2 or later (the "GPL"), or the GNU Lesser General Public | License Version 2.1 or later (the "LGPL"), in which case the provisions of the GPL or the | LGPL License are applicable instead of those above. If you wish to allow use of your version | of this file only under the terms of the GPL or the LGPL License and not to allow others to | use your version of this file under the MPL, indicate your decision by deleting the | provisions above and replace them with the notice and other provisions required by the | GPL or the LGPL License. If you do not delete the provisions above, a recipient may use | your version of this file under either the MPL, the GPL or the LGPL License. | +======================================================================================================+ #### Tags:
version: | 3.3
link: | http://sourceforge.net/projects/phpxpath/
author: | S.Blum / N.Swinson / D.Allen / (P.Mehl)
### XPATH_QUERYHIT_ALL [line 4511]
`XPATH_QUERYHIT_ALL = 1`
********************************************************************************************** =============================================================================================== X P a t h - Class =============================================================================================== ********************************************************************************************** [ Top ] ### XPATH_QUERYHIT_FIRST [line 4512]
`XPATH_QUERYHIT_FIRST = 2`
[ Top ] ### XPATH_QUERYHIT_UNIQUE [line 4513]
`XPATH_QUERYHIT_UNIQUE = 3`
[ Top ] ### _title [line 5600]
`void _title( mixed $title)`
Produces a short title line. [ Top ] Documentation generated on Mon, 29 Dec 2003 21:16:25 +0100 by phpDocumentor 1.2.3