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