1XML::XPath(3) User Contributed Perl Documentation XML::XPath(3)
2
6 XML::XPath - Parse and evaluate XPath statements.
7
9 Version 1.48
10
12 This module aims to comply exactly to the XPath specification at
13 http://www.w3.org/TR/xpath and yet allow extensions to be added in the
14 form of functions.Modules such as XSLT and XPointer may need to do this
15 as they support functionality beyond XPath.
16
18 use XML::XPath;
19 use XML::XPath::XMLParser;
20 my $xp = XML::XPath->new(filename => 'test.xhtml');
22 my $nodeset = $xp->find('/html/body/p'); # find all paragraphs
24 foreach my $node ($nodeset->get_nodelist) {
26 print "FOUND\n\n",
27 XML::XPath::XMLParser::as_string($node),
28 "\n\n";
29 }
30
32 There is an awful lot to all of this, so bear with it - if you stick
33 it out it should be worth it. Please get a good understanding of XPath
34 by reading the spec before asking me questions. All of the classes and
35 parts herein are named to be synonymous with the names in the
36 specification, so consult that if you don't understand why I'm doing
37 something in the code.
38 Currently, it supports XPath 1.0 with a small number of XPath 2.0
40 functions. See XML::XPath::Function for the complete list of predefined
41 functions.
42
44 The API of XML::XPath itself is extremely simple to allow you to get
45 going almost immediately. The deeper API's are more complex, but you
46 shouldn't have to touch most of that.
47 new()
49 This constructor follows the often seen named parameter method call.
50 Parameters you can use are: filename, parser, xml, ioref and context.
51 The filename parameter specifies an XML file to parse. The xml
52 parameter specifies a string to parse, and the ioref parameter
53 specifies an ioref to parse. The context option allows you to
54 specify a context node. The context node has to be in the format of a
55 node as specified in XML::XPath::XMLParser. The 4 parameters
56 filename, xml, ioref and context are mutually exclusive - you should
57 only specify one (if you specify anything other than context, the
58 context node is the root of your document). The parser option allows
59 you to pass in an already prepared XML::Parser object, to save you
60 having to create more than one in your application (if, for example,
61 you are doing more than just XPath).
62 my $xp = XML::XPath->new( context => $node );
64 It is very much recommended that you use only 1 XPath object
66 throughout the life of your application. This is because the object
67 (and it's sub-objects) maintain certain bits of state information
68 that will be useful (such as XPath variables) to later calls to
69 find(). It's also a good idea because you'll use less memory this way.
70 find($path, [$context])
72 The find function takes an XPath expression (a string) and returns
73 either an XML::XPath::NodeSet object containing the nodes it found (or
74 empty if no nodes matched the path), or one of XML::XPath::Literal (a
75 string), XML::XPath::Number or XML::XPath::Boolean. It should always
76 return something - and you can use ->isa() to find out what it
77 returned. If you need to check how many nodes it found you should check
78 $nodeset->size. See XML::XPath::NodeSet. An optional second parameter
79 of a context node allows you to use this method repeatedly, for example
80 XSLT needs to do this.
81 findnodes($path, [$context])
83 Returns a list of nodes found by $path, optionally in context $context.
84 In scalar context returns an XML::XPath::NodeSet object.
85 matches($node, $path, [$context])
87 Returns true if the node matches the path (optionally in context
88 $context).
89 findnodes_as_string($path, [$context])
91 Returns the nodes found reproduced as XML.The result isn't guaranteed
92 to be valid XML though.
93 findvalue($path, [$context])
95 Returns either a "XML::XPath::Literal", a "XML::XPath::Boolean" or a
96 "XML::XPath::Number" object.If the path returns a
97 NodeSet,$nodeset->to_literal is called automatically for you (and thus
98 a "XML::XPath::Literal" is returned).Note that for each of the objects
99 stringification is overloaded, so you can just print the value found,
100 or manipulate it in the ways you would a normal perl value (e.g. using
101 regular expressions).
102 exists($path, [$context])
104 Returns true if the given path exists.
105 getNodeText($path)
107 Returns the XML::XPath::Literal for a particular XML node. Returns a
108 string if exists or '' (empty string) if the node doesn't exist.
109 setNodeText($path, $text)
111 Sets the text string for a particular XML node. The node can be an
112 element or an attribute. If the node to be set is an attribute, and the
113 attribute node does not exist, it will be created automatically.
114 createNode($path)
116 Creates the node matching the $path given. If part of the path given or
117 all of the path do not exist, the necessary nodes will be created
118 automatically.
119 set_namespace($prefix, $uri)
121 Sets the namespace prefix mapping to the uri.
122 Normally in "XML::XPath" the prefixes in XPath node test take their
124 context from the current node. This means that foo:bar will always
125 match an element <foo:bar> regardless of the namespace that the
126 prefix foo is mapped to (which might even change within the document,
127 resulting in unexpected results). In order to make prefixes in XPath
128 node tests actually map to a real URI, you need to enable that via a
129 call to the set_namespace method of your "XML::XPath" object.
130 clear_namespaces()
132 Clears all previously set namespace mappings.
133 $XML::XPath::Namespaces
135 Set this to 0 if you don't want namespace processing to occur. This
136 will make everything a little (tiny) bit faster, but you'll suffer for
137 it, probably.
138
140 See XML::XPath::Node, XML::XPath::Node::Element,
141 XML::XPath::Node::Text, XML::XPath::Node::Comment,
142 XML::XPath::Node::Attribute, XML::XPath::Node::Namespace, and
143 XML::XPath::Node::PI.
144
146 XPath nodes work in a special way that allows circular references, and
147 yet still lets Perl's reference counting garbage collector to clean up
148 the nodes after use. This should be totally transparent to the
149 user, with one caveat: If you free your tree before letting go of a
150 sub-tree,consider that playing with fire and you may get burned. What
151 does this mean to the average user? Not much. Provided you don't free
152 (or let go out of scope) either the tree you passed to XML::XPath->new,
153 or if you didn't pass a tree, and passed a filename or IO-ref, then
154 provided you don't let the XML::XPath object go out of scope before
155 you let results of find() and its friends go out of scope, then
156 you'll be fine. Even if you do let the tree go out of scope before
157 results, you'll probably still be fine. The only case where you may
158 get stung is when the last part of your path/query is either an
159 ancestor or parent axis. In that case the worst that will happen is
160 you'll end up with a circular reference that won't get cleared until
161 interpreter destruction time.You can get around that by explicitly
162 calling $node->DESTROY on each of your result nodes, if you really need
163 to do that.
164 Mail me direct if that's not clear. Note that it's not doom and gloom.
166 It's by no means perfect,but the worst that will happen is a long
167 running process could leak memory. Most long running processes will
168 therefore be able to explicitly be careful not to free the tree (or
169 XML::XPath object) before freeing results.AxKit, an application that
170 uses XML::XPath, does this and I didn't have to make any changes to
171 the code - it's already sensible programming.
172 If you really don't want all this to happen, then set the variable
174 $XML::XPath::SafeMode, and call $xp->cleanup() on the XML::XPath object
175 when you're finished, or $tree->dispose() if you have a tree instead.
176
178 Please see the test files in t/ for examples on how to use XPath.
179
181 Original author Matt Sergeant, "<matt at sergeant.org>"
182 Currently maintained by Mohammad S Anwar, "<mohammad.anwar at
184 yahoo.com>"
185
187 XML::XPath::Function, XML::XPath::Literal, XML::XPath::Boolean,
188 XML::XPath::Number, XML::XPath::XMLParser, XML::XPath::NodeSet,
189 XML::XPath::PerlSAX, XML::XPath::Builder.
190
192 This module is copyright 2000 AxKit.com Ltd. This is free software,
193 and as such comes with NO WARRANTY. No dates are used in this module.
194 You may distribute this module under the terms of either the Gnu GPL,
195 or the Artistic License (the same terms as Perl itself).
196 For support, please subscribe to the Perl-XML
198 <http://listserv.activestate.com/mailman/listinfo/perl-xml> mailing
199 list at the URL
200perl v5.36.0 2023-01-20 XML::XPath(3)