1XML::XPath(3)         User Contributed Perl Documentation        XML::XPath(3)
2
3
4

NAME

6       XML::XPath - Parse and evaluate XPath statements.
7

VERSION

9       Version 1.48
10

DESCRIPTION

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

SYNOPSIS

18           use XML::XPath;
19           use XML::XPath::XMLParser;
20
21           my $xp = XML::XPath->new(filename => 'test.xhtml');
22
23           my $nodeset = $xp->find('/html/body/p'); # find all paragraphs
24
25           foreach my $node ($nodeset->get_nodelist) {
26               print "FOUND\n\n",
27                   XML::XPath::XMLParser::as_string($node),
28                   "\n\n";
29           }
30

DETAILS

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
39       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

METHODS

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
48   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
63           my $xp = XML::XPath->new( context => $node );
64
65       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
71   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
82   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
86   matches($node, $path, [$context])
87       Returns true if the node matches the path (optionally in context
88       $context).
89
90   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
94   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
103   exists($path, [$context])
104       Returns true if the given path exists.
105
106   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
110   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
115   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
120   set_namespace($prefix, $uri)
121       Sets the namespace prefix mapping to the uri.
122
123       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
131   clear_namespaces()
132       Clears all previously set namespace mappings.
133
134   $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

Node Object Model

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

On Garbage Collection

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
165       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
173       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

Example

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

AUTHOR

181       Original author Matt Sergeant, "<matt at sergeant.org>"
182
183       Currently maintained by Mohammad S Anwar, "<mohammad.anwar at
184       yahoo.com>"
185

SEE ALSO

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
197       For support, please subscribe to the Perl-XML
198       <http://listserv.activestate.com/mailman/listinfo/perl-xml> mailing
199       list at the URL
200
201
202
203perl v5.36.0                      2023-01-20                     XML::XPath(3)
Impressum