hxt-7.5: A collection of tools for processing XML with Haskell.ContentsIndex
Text.XML.HXT.Arrow.XPath
Portabilityportable
Stabilityexperimental
MaintainerUwe Schmidt (uwe@fh-wedel.de)
Description

Arrows for working with XPath and XmlNodeSets.

Most of the XPath arrows come in two versions, one without dealing with namespaces, element and attribute names in XPath expressions are taken as they ar ignoring any prefix:localname structure.

The second variant uses a namespace environment for associating the right namespace for the appropriate prefix. an entry for the empty prefix defines the default namespace for the expression.

The second variant should be used, when in the application namespaces are significant, that means when namespace propagation is done for the documents to be processed.

NodeSets are sets of "pointer" into an XML tree to reference subnodes. These nodesets can be computed by XPath expressions or normal arrows. The nodesets can then be used later for selecting or modifying subtrees of this tree in an efficient way.

Synopsis
getXPathTreesInDoc :: ArrowXml a => String -> a XmlTree XmlTree
getXPathTreesInDocWithNsEnv :: ArrowXml a => NsEnv -> String -> a XmlTree XmlTree
getXPathTrees :: ArrowXml a => String -> a XmlTree XmlTree
getXPathTreesWithNsEnv :: ArrowXml a => NsEnv -> String -> a XmlTree XmlTree
getElemNodeSet :: ArrowXml a => a XmlTree XmlTree -> a XmlTree XmlNodeSet
getElemAndAttrNodeSet :: ArrowXml a => a XmlTree XmlTree -> a XmlTree XmlNodeSet
getXPathNodeSet :: ArrowXml a => String -> a XmlTree XmlNodeSet
getFromNodeSet :: ArrowXml a => XmlNodeSet -> a XmlTree XmlTree
processXPathTrees :: ArrowXml a => a XmlTree XmlTree -> String -> a XmlTree XmlTree
processXPathTreesWithNsEnv :: ArrowXml a => a XmlTree XmlTree -> NsEnv -> String -> a XmlTree XmlTree
processFromNodeSet :: ArrowXml a => a XmlTree XmlTree -> XmlNodeSet -> a XmlTree XmlTree
Documentation
getXPathTreesInDoc :: ArrowXml a => String -> a XmlTree XmlTree

Select parts of a whole XML document with root node by a XPath expression.

The main filter for selecting parts of a document via XPath.

The string argument must be a XPath expression with an absolute location path, the argument tree must be a complete document tree.

Before evaluating the xpath query, the document is canonicalized with canonicalizeForXPath

Result is a possibly empty list of XmlTrees forming the set of selected XPath values. XPath values other than XmlTrees (numbers, attributes, tagnames, ...) are convertet to text nodes.

getXPathTreesInDocWithNsEnv :: ArrowXml a => NsEnv -> String -> a XmlTree XmlTree
Same as getXPathTreesInDoc but with namespace environment for the XPath names
getXPathTrees :: ArrowXml a => String -> a XmlTree XmlTree

Select parts of an arbitrary XML tree by a XPath expression.

The main filter for selecting parts of an arbitrary XML tree via XPath. The string argument must be a XPath expression with an absolute location path, There are no restrictions on the argument tree.

No canonicalization is performed before evaluating the query

Result is a possibly empty list of XmlTrees forming the set of selected XPath values. XPath values other than XmlTrees (numbers, attributes, tagnames, ...) are convertet to text nodes.

getXPathTreesWithNsEnv :: ArrowXml a => NsEnv -> String -> a XmlTree XmlTree
Same as getXPathTrees but with namespace environment for the XPath names
getElemNodeSet :: ArrowXml a => a XmlTree XmlTree -> a XmlTree XmlNodeSet

compute a node set from a tree, containing all nodes selected by the predicate arrow

computation of the set of element nodes with name "a" is done with

 getElemNodeSet (hasName "a")
getElemAndAttrNodeSet :: ArrowXml a => a XmlTree XmlTree -> a XmlTree XmlNodeSet
compute a node set from a tree, containing all nodes including attribute nodes elected by the predicate arrow
getXPathNodeSet :: ArrowXml a => String -> a XmlTree XmlNodeSet

Select a set of nodes via an XPath expression from an arbitray XML tree

The result is a set of "pointers" to nodes. This set can be used to access or modify the values of the subnodes in subsequent calls to getFromNodeSet or processFromNodeSet.

This function enables for parsing an XPath expressions and traversing the tree for node selection once and reuse this result possibly many times for later selection and modification operations.

getFromNodeSet :: ArrowXml a => XmlNodeSet -> a XmlTree XmlTree

select all subtrees specified by a previously computed node set

the following law holds:

 getFromNodeSet $< getElemNodeSet f == multi f
processXPathTrees :: ArrowXml a => a XmlTree XmlTree -> String -> a XmlTree XmlTree

process all subtrees selected by an XPath expression

the following law holds:

 processXPathTrees p xpathExpr == processFromNodeSet p $< getXPathNodeSet xpathExpr
processXPathTreesWithNsEnv :: ArrowXml a => a XmlTree XmlTree -> NsEnv -> String -> a XmlTree XmlTree
Same as processXPathTrees but with namespace environment for the XPath names
processFromNodeSet :: ArrowXml a => a XmlTree XmlTree -> XmlNodeSet -> a XmlTree XmlTree

process all subtrees specified by a previously computed node set in bottom up manner

the follwoing law holds:

 processFromNodeSet g $< getElemNodeSet f == processBottomUp (g `when` f)

when attributes are contained in the node set (see getElemAndAttrNodeSet), these are processed after the children and before the node itself

the advantage of processFromNodeSet is the separation of the selection of set of nodes to be processed (e.g. modified) from the real proccessing. The selection sometimes can be done once, the processing possibly many times.

Produced by Haddock version 2.1.0