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
10       module/classes that implement trees.
11
12       In order to use the XPath engine, nodes in the user module need to
13       mimick DOM nodes. The degree of similitude between the user tree and a
14       DOM dictates how much of the XPath features can be used. A module
15       implementing all of the DOM should be able to use this module very
16       easily (you might need to add the cmp method on nodes in order to get
17       ordered 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,
25       http://www.xmltwig.com/article/extending_xml_xpath/ should give authors
26       who want to use this module enough 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   findnodes ($path, $context)
51       Returns a list of nodes found by $path, optionally in context $context.
52       In scalar context returns an XML::XPathEngine::NodeSet object.
53
54   findnodes_as_string ($path, $context)
55       Returns the nodes found as a single string. The result is not
56       guaranteed to be valid XML though (it could for example be just text if
57       the query returns attribute values).
58
59   findnodes_as_strings ($path, $context)
60       Returns the nodes found as a list of strings, one per node found.
61
62   findvalue ($path, $context)
63       Returns the result as a string (the concatenation of the values of the
64       result nodes).
65
66   findvalues($path, $context)
67       Returns the values of the result nodes as a list of strings.
68
69   exists ($path, $context)
70       Returns true if the given path exists.
71
72   matches($node, $path, $context)
73       Returns true if the node matches the path.
74
75   find ($path, $context)
76       The find function takes an XPath expression (a string) and returns
77       either a XML::XPathEngine::NodeSet object containing the nodes it found
78       (or empty if no nodes matched the path), or one of
79       XML::XPathEngine::Literal (a string), XML::XPathEngine::Number, or
80       XML::XPathEngine::Boolean. It should always return something - and you
81       can use ->isa() to find out what it returned. If you need to check how
82       many nodes it found you should check $nodeset->size.  See
83       XML::XPathEngine::NodeSet.
84
85   getNodeText ($path)
86       Returns the text string for a particular node. Returns a string, or
87       undef if the node doesn't exist.
88
89   set_namespace ($prefix, $uri)
90       Sets the namespace prefix mapping to the uri.
91
92       Normally in XML::XPathEngine the prefixes in XPath node tests take
93       their context from the current node. This means that foo:bar will
94       always match an element <foo:bar> regardless of the namespace that the
95       prefix foo is mapped to (which might even change within the document,
96       resulting in unexpected results). In order to make prefixes in XPath
97       node tests actually map to a real URI, you need to enable that via a
98       call to the set_namespace method of your XML::XPathEngine object.
99
100   clear_namespaces ()
101       Clears all previously set namespace mappings.
102
103   get_namespace ($prefix, $node)
104       Returns the uri associated to the prefix for the node (mostly for
105       internal usage)
106
107   set_strict_namespaces ($strict)
108       By default, for historical as well as convenience reasons,
109       XML::XPathEngine has a slightly non-standard way of dealing with the
110       default namespace.
111
112       If you search for "//tag" it will return elements "tag". As far as I
113       understand it, if the document has a default namespace, this should not
114       return anything.  You would have to first do a "set_namespace", and
115       then search using the namespace.
116
117       Passing a true value to "set_strict_namespaces" will activate this
118       behaviour, passing a false value will return it to its default
119       behaviour.
120
121   set_var ($var. $val)
122       Sets an XPath variable (that can be used in queries as $var)
123
124   get_var ($var)
125       Returns the value of the XPath variable (mostly for internal usage)
126
127   $XML::XPathEngine::Namespaces
128       Set this to 0 if you don't want namespace processing to occur. This
129       will make everything a little (tiny) bit faster, but you'll suffer for
130       it, probably.
131

Node Object Model
133       Nodes need to provide the same API as nodes in XML::XPath (at least the
134       access API, not the tree manipulation one).
135

Example
137       Please see the test files in t/ for examples on how to use XPath.
138

XPath extension
140       The module supports the XPath recommendation to the same extend as
141       XML::XPath (that is, rather completely).
142
143       It includes a perl-specific extension: direct support for regular
144       expressions.
145
146       You can use the usual (in Perl!) "=~" and "!~" operators. Regular
147       expressions are / delimited (no other delimiter is accepted, \ inside
148       regexp must be backslashed), the "imsx" modifiers can be used.
149
150         $xp->findnodes( '//@att[.=~ /^v.$/]'); # returns the list of attributes att
151                                                # whose value matches ^v.$
152

SEE ALSO
154       XML::XPath
155
156       HTML::TreeBuilder::XPath, XML::Twig::XPath for exemples of using this
157       module
158
159       Tree::XPathEngine for a similar module for non-XML trees.
160
161       <http://www.xmltwig.com/article/extending_xml_xpath/> for background
162       information. The last section of the article summarizes how to reuse
163       XML::XPath.  As XML::XPathEngine offers the same API it should help you
164

AUTHOR
166       Michel Rodriguez, "<mirod@cpan.org>" Most code comes directly from
167       XML::XPath, by Matt Sergeant.
168

BUGS
170       Please report any bugs or feature requests to
171       "bug-tree-xpathengine@rt.cpan.org", or through the web interface at
172       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML-XPathEngine>.  I
173       will be notified, and then you'll automatically be notified of progress
174       on your bug as I make changes.
175

ACKNOWLEDGEMENTS
178       XML::XPath Copyright 2000 AxKit.com Ltd.  Copyright 2006 Michel
179       Rodriguez, All Rights Reserved.
180
181       This program is free software; you can redistribute it and/or modify it
182       under the same terms as Perl itself.
183
184
185
186perl v5.34.0                      2022-01-21               XML::XPathEngine(3)



        

    


            
        

        

            Impressum