1XPATH(1)              User Contributed Perl Documentation             XPATH(1)
2
3
4

NAME

6       xpath - a script to query XPath statements in XML documents.
7

SYNOPSIS

9       xpath [-s suffix] [-p prefix] [-n] [-q] -e query [-e query] ... [file]
10       ...
11

DESCRIPTION

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
18       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
22       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

OPTIONS

28   -q
29       Be quiet. Output only errors (and no separator) on stderr.
30
31   -n
32       Never use an external DTD, ie. instantiate the XML::Parser module with
33       'ParseParamEnt => 0'.
34
35   -s suffix
36       Place "suffix" at the end of each entry. Default is a linefeed.
37
38   -p prefix
39       Place "prefix" preceding each entry. Default is nothing.
40

BUGS

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

SEE ALSO

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
54       For support, please subscribe to the Perl-XML
55       <http://listserv.activestate.com/mailman/listinfo/perl-xml> mailing
56       list at the URL
57
58
59
60XML::XPath(3)         User Contributed Perl Documentation        XML::XPath(3)
61
62
63

NAME

65       XML::XPath - Parse and evaluate XPath statements.
66

VERSION

68       Version 1.44
69

DESCRIPTION

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

SYNOPSIS

77           use XML::XPath;
78           use XML::XPath::XMLParser;
79
80           my $xp = XML::XPath->new(filename => 'test.xhtml');
81
82           my $nodeset = $xp->find('/html/body/p'); # find all paragraphs
83
84           foreach my $node ($nodeset->get_nodelist) {
85               print "FOUND\n\n",
86                   XML::XPath::XMLParser::as_string($node),
87                   "\n\n";
88           }
89

DETAILS

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

METHODS

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
103   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
118           my $xp = XML::XPath->new( context => $node );
119
120       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
126   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
137   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
141   matches($node, $path, [$context])
142       Returns true if the node matches the path (optionally in context
143       $context).
144
145   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
149   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
158   exists($path, [$context])
159       Returns true if the given path exists.
160
161   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
165   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
170   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
175   set_namespace($prefix, $uri)
176       Sets the namespace prefix mapping to the uri.
177
178       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
186   clear_namespaces()
187       Clears all previously set namespace mappings.
188
189   $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

Node Object Model

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

On Garbage Collection

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
220       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
228       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

Example

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

AUTHOR

236       Original author Matt Sergeant, "<matt at sergeant.org>"
237
238       Currently maintained by Mohammad S Anwar, "<mohammad.anwar at
239       yahoo.com>"
240

SEE ALSO

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
252       For support, please subscribe to the Perl-XML
253       <http://listserv.activestate.com/mailman/listinfo/perl-xml> mailing
254       list at the URL
255
256
257
258perl v5.34.0                      2022-01-21                     XML::XPath(3)
Impressum