1XPATH(1) User Contributed Perl Documentation XPATH(1)
2
6 xpath - a script to query XPath statements in XML documents.
7
9 xpath [-s suffix] [-p prefix] [-n] [-q] -e query [-e query] ... [file]
10 ...
11
13 xpath uses the XML::XPath perl module to make XPath queries to any XML
14 document. The XML::XPath module aims to comply exactly to the XPath
15 specification at "http://www.w3.org/TR/xpath" and yet allows extensions
16 to be added in the form of functions.
17 The script takes any number of XPath pointers and tries to apply them
19 to each XML document given on the command line. If no file arguments
20 are given, the query is done using "STDIN" as an XML document.
21 When multiple queries exist, the result of the last query is used as
23 context for the next query and only the result of the last one is
24 output. The context of the first query is always the root of the
25 current document.
26
28 -q
29 Be quiet. Output only errors (and no separator) on stderr.
30 -n
32 Never use an external DTD, ie. instantiate the XML::Parser module with
33 'ParseParamEnt => 0'.
34 -s suffix
36 Place "suffix" at the end of each entry. Default is a linefeed.
37 -p prefix
39 Place "prefix" preceding each entry. Default is nothing.
40
42 The author of this man page is not very fluant in english. Please, send
43 him (fabien@tzone.org) any corrections concerning this text.
44
46 XML::XPath
47
49 This module is copyright 2000 AxKit.com Ltd. This is free software,
50 and as such comes with NO WARRANTY. No dates are used in this module.
51 You may distribute this module under the terms of either the Gnu GPL,
52 or the Artistic License (the same terms as Perl itself).
53 For support, please subscribe to the Perl-XML
55 <http://listserv.activestate.com/mailman/listinfo/perl-xml> mailing
56 list at the URL
57XML::XPath(3) User Contributed Perl Documentation XML::XPath(3)
61
65 XML::XPath - Parse and evaluate XPath statements.
66
68 Version 1.48
69
71 This module aims to comply exactly to the XPath specification at
72 http://www.w3.org/TR/xpath and yet allow extensions to be added in the
73 form of functions.Modules such as XSLT and XPointer may need to do this
74 as they support functionality beyond XPath.
75
77 use XML::XPath;
78 use XML::XPath::XMLParser;
79 my $xp = XML::XPath->new(filename => 'test.xhtml');
81 my $nodeset = $xp->find('/html/body/p'); # find all paragraphs
83 foreach my $node ($nodeset->get_nodelist) {
85 print "FOUND\n\n",
86 XML::XPath::XMLParser::as_string($node),
87 "\n\n";
88 }
89
91 There is an awful lot to all of this, so bear with it - if you stick
92 it out it should be worth it. Please get a good understanding of XPath
93 by reading the spec before asking me questions. All of the classes and
94 parts herein are named to be synonymous with the names in the
95 specification, so consult that if you don't understand why I'm doing
96 something in the code.
97 Currently, it supports XPath 1.0 with a small number of XPath 2.0
99 functions. See XML::XPath::Function for the complete list of predefined
100 functions.
101
103 The API of XML::XPath itself is extremely simple to allow you to get
104 going almost immediately. The deeper API's are more complex, but you
105 shouldn't have to touch most of that.
106 new()
108 This constructor follows the often seen named parameter method call.
109 Parameters you can use are: filename, parser, xml, ioref and context.
110 The filename parameter specifies an XML file to parse. The xml
111 parameter specifies a string to parse, and the ioref parameter
112 specifies an ioref to parse. The context option allows you to
113 specify a context node. The context node has to be in the format of a
114 node as specified in XML::XPath::XMLParser. The 4 parameters
115 filename, xml, ioref and context are mutually exclusive - you should
116 only specify one (if you specify anything other than context, the
117 context node is the root of your document). The parser option allows
118 you to pass in an already prepared XML::Parser object, to save you
119 having to create more than one in your application (if, for example,
120 you are doing more than just XPath).
121 my $xp = XML::XPath->new( context => $node );
123 It is very much recommended that you use only 1 XPath object
125 throughout the life of your application. This is because the object
126 (and it's sub-objects) maintain certain bits of state information
127 that will be useful (such as XPath variables) to later calls to
128 find(). It's also a good idea because you'll use less memory this way.
129 find($path, [$context])
131 The find function takes an XPath expression (a string) and returns
132 either an XML::XPath::NodeSet object containing the nodes it found (or
133 empty if no nodes matched the path), or one of XML::XPath::Literal (a
134 string), XML::XPath::Number or XML::XPath::Boolean. It should always
135 return something - and you can use ->isa() to find out what it
136 returned. If you need to check how many nodes it found you should check
137 $nodeset->size. See XML::XPath::NodeSet. An optional second parameter
138 of a context node allows you to use this method repeatedly, for example
139 XSLT needs to do this.
140 findnodes($path, [$context])
142 Returns a list of nodes found by $path, optionally in context $context.
143 In scalar context returns an XML::XPath::NodeSet object.
144 matches($node, $path, [$context])
146 Returns true if the node matches the path (optionally in context
147 $context).
148 findnodes_as_string($path, [$context])
150 Returns the nodes found reproduced as XML.The result isn't guaranteed
151 to be valid XML though.
152 findvalue($path, [$context])
154 Returns either a "XML::XPath::Literal", a "XML::XPath::Boolean" or a
155 "XML::XPath::Number" object.If the path returns a
156 NodeSet,$nodeset->to_literal is called automatically for you (and thus
157 a "XML::XPath::Literal" is returned).Note that for each of the objects
158 stringification is overloaded, so you can just print the value found,
159 or manipulate it in the ways you would a normal perl value (e.g. using
160 regular expressions).
161 exists($path, [$context])
163 Returns true if the given path exists.
164 getNodeText($path)
166 Returns the XML::XPath::Literal for a particular XML node. Returns a
167 string if exists or '' (empty string) if the node doesn't exist.
168 setNodeText($path, $text)
170 Sets the text string for a particular XML node. The node can be an
171 element or an attribute. If the node to be set is an attribute, and the
172 attribute node does not exist, it will be created automatically.
173 createNode($path)
175 Creates the node matching the $path given. If part of the path given or
176 all of the path do not exist, the necessary nodes will be created
177 automatically.
178 set_namespace($prefix, $uri)
180 Sets the namespace prefix mapping to the uri.
181 Normally in "XML::XPath" the prefixes in XPath node test take their
183 context from the current node. This means that foo:bar will always
184 match an element <foo:bar> regardless of the namespace that the
185 prefix foo is mapped to (which might even change within the document,
186 resulting in unexpected results). In order to make prefixes in XPath
187 node tests actually map to a real URI, you need to enable that via a
188 call to the set_namespace method of your "XML::XPath" object.
189 clear_namespaces()
191 Clears all previously set namespace mappings.
192 $XML::XPath::Namespaces
194 Set this to 0 if you don't want namespace processing to occur. This
195 will make everything a little (tiny) bit faster, but you'll suffer for
196 it, probably.
197
199 See XML::XPath::Node, XML::XPath::Node::Element,
200 XML::XPath::Node::Text, XML::XPath::Node::Comment,
201 XML::XPath::Node::Attribute, XML::XPath::Node::Namespace, and
202 XML::XPath::Node::PI.
203
205 XPath nodes work in a special way that allows circular references, and
206 yet still lets Perl's reference counting garbage collector to clean up
207 the nodes after use. This should be totally transparent to the
208 user, with one caveat: If you free your tree before letting go of a
209 sub-tree,consider that playing with fire and you may get burned. What
210 does this mean to the average user? Not much. Provided you don't free
211 (or let go out of scope) either the tree you passed to XML::XPath->new,
212 or if you didn't pass a tree, and passed a filename or IO-ref, then
213 provided you don't let the XML::XPath object go out of scope before
214 you let results of find() and its friends go out of scope, then
215 you'll be fine. Even if you do let the tree go out of scope before
216 results, you'll probably still be fine. The only case where you may
217 get stung is when the last part of your path/query is either an
218 ancestor or parent axis. In that case the worst that will happen is
219 you'll end up with a circular reference that won't get cleared until
220 interpreter destruction time.You can get around that by explicitly
221 calling $node->DESTROY on each of your result nodes, if you really need
222 to do that.
223 Mail me direct if that's not clear. Note that it's not doom and gloom.
225 It's by no means perfect,but the worst that will happen is a long
226 running process could leak memory. Most long running processes will
227 therefore be able to explicitly be careful not to free the tree (or
228 XML::XPath object) before freeing results.AxKit, an application that
229 uses XML::XPath, does this and I didn't have to make any changes to
230 the code - it's already sensible programming.
231 If you really don't want all this to happen, then set the variable
233 $XML::XPath::SafeMode, and call $xp->cleanup() on the XML::XPath object
234 when you're finished, or $tree->dispose() if you have a tree instead.
235
237 Please see the test files in t/ for examples on how to use XPath.
238
240 Original author Matt Sergeant, "<matt at sergeant.org>"
241 Currently maintained by Mohammad S Anwar, "<mohammad.anwar at
243 yahoo.com>"
244
246 XML::XPath::Function, XML::XPath::Literal, XML::XPath::Boolean,
247 XML::XPath::Number, XML::XPath::XMLParser, XML::XPath::NodeSet,
248 XML::XPath::PerlSAX, XML::XPath::Builder.
249
251 This module is copyright 2000 AxKit.com Ltd. This is free software,
252 and as such comes with NO WARRANTY. No dates are used in this module.
253 You may distribute this module under the terms of either the Gnu GPL,
254 or the Artistic License (the same terms as Perl itself).
255 For support, please subscribe to the Perl-XML
257 <http://listserv.activestate.com/mailman/listinfo/perl-xml> mailing
258 list at the URL
259perl v5.38.0 2023-07-21 XML::XPath(3)