XML::XPathEngine(3pm)

1XML::XPathEngine(3)   User Contributed Perl Documentation  XML::XPathEngine(3)
2
3
4

NAME

6       XML::XPathEngine - a re-usable XPath engine for DOM-like trees
7

DESCRIPTION

9       This module provides an XPath engine, that can be re-used by other mod‐
10       ule/classes that implement trees.
11
12       In order to use the XPath engine, nodes in the user module need to mim‐
13       ick DOM nodes. The degree of similitude between the user tree and a DOM
14       dictates how much of the XPath features can be used. A module imple‐
15       menting all of the DOM should be able to use this module very easily
16       (you might need to add the cmp method on nodes in order to get ordered
17       result sets).
18
19       This code is a more or less direct copy of the XML::XPath module by
20       Matt Sergeant. I only removed the XML processing part to remove the
21       dependency on XML::Parser, applied a couple of patches, renamed a whole
22       lot of methods to make Pod::Coverage happy, and changed the docs.
23
24       The article eXtending XML XPath, http://www.xmltwig.com/article/extend‐
25       ing_xml_xpath/ should give authors who want to use this module enough
26       background to do so.
27
28       Otherwise, my email is below ;--)
29
30       WARNING: while the underlying code is rather solid, this module mostly
31       lacks docs.  As they say, "patches welcome"...
32

SYNOPSIS

34           use XML::XPathEngine;
35
36           my $tree= my_tree->new( ...);
37           my $xp = XML::XPathEngine->new();
38
39           my @nodeset = $xp->find('/root/kid/grandkid[1]', $tree); # find all first grankids
40
41           package XML::MyTree;
42
43           # needs to provide DOM methods
44

DETAILS

API

47       XML::XPathEngine will provide the following methods:
48
49       new
50
51       findnodes ($path, $context)
52
53       Returns a list of nodes found by $path, optionally in context $context.
54       In scalar context returns an XML::XPathEngine::NodeSet object.
55
56       findnodes_as_string ($path, $context)
57
58       Returns the nodes found as a single string. The result is not guaran‐
59       teed to be valid XML though (it could for example be just text if the
60       query returns attribute values).
61
62       findnodes_as_strings ($path, $context)
63
64       Returns the nodes found as a list of strings, one per node found.
65
66       findvalue ($path, $context)
67
68       Returns the result as a string (the concatenation of the values of the
69       result nodes).
70
71       exists ($path, $context)
72
73       Returns true if the given path exists.
74
75       matches($node, $path, $context)
76
77       Returns true if the node matches the path.
78
79       find ($path, $context)
80
81       The find function takes an XPath expression (a string) and returns
82       either a XML::XPathEngine::NodeSet object containing the nodes it found
83       (or empty if no nodes matched the path), or one of XML::XPa‐
84       thEngine::Literal (a string), XML::XPathEngine::Number, or XML::XPa‐
85       thEngine::Boolean. It should always return something - and you can use
86       ->isa() to find out what it returned. If you need to check how many
87       nodes it found you should check $nodeset->size.  See XML::XPa‐
88       thEngine::NodeSet.
89
90       getNodeText ($path)
91
92       Returns the text string for a particular node. Returns a string, or
93       undef if the node doesn't exist.
94
95       set_namespace ($prefix, $uri)
96
97       Sets the namespace prefix mapping to the uri.
98
99       Normally in XML::XPathEngine the prefixes in XPath node tests take
100       their context from the current node. This means that foo:bar will
101       always match an element <foo:bar> regardless of the namespace that the
102       prefix foo is mapped to (which might even change within the document,
103       resulting in unexpected results). In order to make prefixes in XPath
104       node tests actually map to a real URI, you need to enable that via a
105       call to the set_namespace method of your XML::XPathEngine object.
106
107       clear_namespaces ()
108
109       Clears all previously set namespace mappings.
110
111       get_namespace ($prefix, $node)
112
113       Returns the uri associated to the prefix for the node (mostly for
114       internal usage)
115
116       set_strict_namespaces ($strict)
117
118       By default, for historical as well as convenience reasons, XML::XPa‐
119       thEngine has a slightly non-standard way of dealing with the default
120       namespace.
121
122       If you search for "//tag" it will return elements "tag". As far as I
123       understand it, if the document has a default namespace, this should not
124       return anything.  You would have to first do a "set_namespace", and
125       then search using the namespace.
126
127       Passing a true value to "set_strict_namespaces" will activate this be‐
128       haviour, passing a false value will return it to its default behaviour.
129
130       set_var ($var. $val)
131
132       Sets an XPath variable (that can be used in queries as $var)
133
134       get_var ($var)
135
136       Returns the value of the XPath variable (mostly for internal usage)
137
138       $XML::XPathEngine::Namespaces
139
140       Set this to 0 if you don't want namespace processing to occur. This
141       will make everything a little (tiny) bit faster, but you'll suffer for
142       it, probably.
143

Node Object Model

145       Nodes need to provide the same API as nodes in XML::XPath (at least the
146       access API, not the tree manipulation one).
147

Example

149       Please see the test files in t/ for examples on how to use XPath.
150

XPath extension

152       The module supports the XPath recommendation to the same extend as
153       XML::XPath (that is, rather completely).
154
155       It includes a perl-specific extension: direct support for regular
156       expressions.
157
158       You can use the usual (in Perl!) "=~" and "!~" operators. Regular
159       expressions are / delimited (no other delimiter is accepted, \ inside
160       regexp must be backslashed), the "imsx" modifiers can be used.
161
162         $xp->findnodes( '//@att[.=~ /^v.$/]'); # returns the list of attributes att
163                                                # whose value matches ^v.$
164

AUTHOR

178       Michel Rodriguez, "<mirod@cpan.org>" Most code comes directly from
179       XML::XPath, by Matt Sergeant.
180

BUGS

182       Please report any bugs or feature requests to "bug-tree-xpa‐
183       thengine@rt.cpan.org", or through the web interface at
184       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML-XPathEngine>.  I
185       will be notified, and then you'll automatically be notified of progress
186       on your bug as I make changes.
187

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

190       XML::XPath Copyright 2000 AxKit.com Ltd.  Copyright 2006 Michel
191       Rodriguez, All Rights Reserved.
192
193       This program is free software; you can redistribute it and/or modify it
194       under the same terms as Perl itself.
195
196
197
198perl v5.8.8                       2008-04-14               XML::XPathEngine(3)