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.44
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
99 The API of XML::XPath itself is extremely simple to allow you to get
100 going almost immediately. The deeper API's are more complex, but you
101 shouldn't have to touch most of that.
102 new()
104 This constructor follows the often seen named parameter method call.
105 Parameters you can use are: filename, parser, xml, ioref and context.
106 The filename parameter specifies an XML file to parse. The xml
107 parameter specifies a string to parse, and the ioref parameter
108 specifies an ioref to parse. The context option allows you to
109 specify a context node. The context node has to be in the format of a
110 node as specified in XML::XPath::XMLParser. The 4 parameters
111 filename, xml, ioref and context are mutually exclusive - you should
112 only specify one (if you specify anything other than context, the
113 context node is the root of your document). The parser option allows
114 you to pass in an already prepared XML::Parser object, to save you
115 having to create more than one in your application (if, for example,
116 you are doing more than just XPath).
117 my $xp = XML::XPath->new( context => $node );
119 It is very much recommended that you use only 1 XPath object
121 throughout the life of your application. This is because the object
122 (and it's sub-objects) maintain certain bits of state information
123 that will be useful (such as XPath variables) to later calls to
124 find(). It's also a good idea because you'll use less memory this way.
125 find($path, [$context])
127 The find function takes an XPath expression (a string) and returns
128 either an XML::XPath::NodeSet object containing the nodes it found (or
129 empty if no nodes matched the path), or one of XML::XPath::Literal (a
130 string), XML::XPath::Number or XML::XPath::Boolean. It should always
131 return something - and you can use ->isa() to find out what it
132 returned. If you need to check how many nodes it found you should check
133 $nodeset->size. See XML::XPath::NodeSet. An optional second parameter
134 of a context node allows you to use this method repeatedly, for example
135 XSLT needs to do this.
136 findnodes($path, [$context])
138 Returns a list of nodes found by $path, optionally in context $context.
139 In scalar context returns an XML::XPath::NodeSet object.
140 matches($node, $path, [$context])
142 Returns true if the node matches the path (optionally in context
143 $context).
144 findnodes_as_string($path, [$context])
146 Returns the nodes found reproduced as XML.The result isn't guaranteed
147 to be valid XML though.
148 findvalue($path, [$context])
150 Returns either a "XML::XPath::Literal", a "XML::XPath::Boolean" or a
151 "XML::XPath::Number" object.If the path returns a
152 NodeSet,$nodeset->to_literal is called automatically for you (and thus
153 a "XML::XPath::Literal" is returned).Note that for each of the objects
154 stringification is overloaded, so you can just print the value found,
155 or manipulate it in the ways you would a normal perl value (e.g. using
156 regular expressions).
157 exists($path, [$context])
159 Returns true if the given path exists.
160 getNodeText($path)
162 Returns the XML::XPath::Literal for a particular XML node. Returns a
163 string if exists or '' (empty string) if the node doesn't exist.
164 setNodeText($path, $text)
166 Sets the text string for a particular XML node. The node can be an
167 element or an attribute. If the node to be set is an attribute, and the
168 attribute node does not exist, it will be created automatically.
169 createNode($path)
171 Creates the node matching the $path given. If part of the path given or
172 all of the path do not exist, the necessary nodes will be created
173 automatically.
174 set_namespace($prefix, $uri)
176 Sets the namespace prefix mapping to the uri.
177 Normally in "XML::XPath" the prefixes in XPath node test take their
179 context from the current node. This means that foo:bar will always
180 match an element <foo:bar> regardless of the namespace that the
181 prefix foo is mapped to (which might even change within the document,
182 resulting in unexpected results). In order to make prefixes in XPath
183 node tests actually map to a real URI, you need to enable that via a
184 call to the set_namespace method of your "XML::XPath" object.
185 clear_namespaces()
187 Clears all previously set namespace mappings.
188 $XML::XPath::Namespaces
190 Set this to 0 if you don't want namespace processing to occur. This
191 will make everything a little (tiny) bit faster, but you'll suffer for
192 it, probably.
193
195 See XML::XPath::Node, XML::XPath::Node::Element,
196 XML::XPath::Node::Text, XML::XPath::Node::Comment,
197 XML::XPath::Node::Attribute, XML::XPath::Node::Namespace, and
198 XML::XPath::Node::PI.
199
201 XPath nodes work in a special way that allows circular references, and
202 yet still lets Perl's reference counting garbage collector to clean up
203 the nodes after use. This should be totally transparent to the
204 user, with one caveat: If you free your tree before letting go of a
205 sub-tree,consider that playing with fire and you may get burned. What
206 does this mean to the average user? Not much. Provided you don't free
207 (or let go out of scope) either the tree you passed to XML::XPath->new,
208 or if you didn't pass a tree, and passed a filename or IO-ref, then
209 provided you don't let the XML::XPath object go out of scope before
210 you let results of find() and its friends go out of scope, then
211 you'll be fine. Even if you do let the tree go out of scope before
212 results, you'll probably still be fine. The only case where you may
213 get stung is when the last part of your path/query is either an
214 ancestor or parent axis. In that case the worst that will happen is
215 you'll end up with a circular reference that won't get cleared until
216 interpreter destruction time.You can get around that by explicitly
217 calling $node->DESTROY on each of your result nodes, if you really need
218 to do that.
219 Mail me direct if that's not clear. Note that it's not doom and gloom.
221 It's by no means perfect,but the worst that will happen is a long
222 running process could leak memory. Most long running processes will
223 therefore be able to explicitly be careful not to free the tree (or
224 XML::XPath object) before freeing results.AxKit, an application that
225 uses XML::XPath, does this and I didn't have to make any changes to
226 the code - it's already sensible programming.
227 If you really don't want all this to happen, then set the variable
229 $XML::XPath::SafeMode, and call $xp->cleanup() on the XML::XPath object
230 when you're finished, or $tree->dispose() if you have a tree instead.
231
233 Please see the test files in t/ for examples on how to use XPath.
234
236 Original author Matt Sergeant, "<matt at sergeant.org>"
237 Currently maintained by Mohammad S Anwar, "<mohammad.anwar at
239 yahoo.com>"
240
242 XML::XPath::Literal, XML::XPath::Boolean, XML::XPath::Number,
243 XML::XPath::XMLParser, XML::XPath::NodeSet, XML::XPath::PerlSAX,
244 XML::XPath::Builder.
245
247 This module is copyright 2000 AxKit.com Ltd. This is free software,
248 and as such comes with NO WARRANTY. No dates are used in this module.
249 You may distribute this module under the terms of either the Gnu GPL,
250 or the Artistic License (the same terms as Perl itself).
251 For support, please subscribe to the Perl-XML
253 <http://listserv.activestate.com/mailman/listinfo/perl-xml> mailing
254 list at the URL
255perl v5.34.0 2022-01-21 XML::XPath(3)