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