.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "XML::XPathEngine 3pm"
.TH XML::XPathEngine 3pm "2018-01-01" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::XPathEngine \- a re\-usable XPath engine for DOM\-like trees
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an XPath engine, that can be re-used by other
module/classes that implement trees.
.PP
In order to use the XPath engine, nodes in the user module need to mimic
\&\s-1DOM\s0 nodes. The degree of similitude between the user tree and a \s-1DOM\s0 dictates 
how much of the XPath features can be used. A module implementing all of the
\&\s-1DOM\s0 should be able to use this module very easily (you might need to add
the cmp method on nodes in order to get ordered result sets).
.PP
This code is a more or less direct copy of the XML::XPath module by
Matt Sergeant. I only removed the \s-1XML\s0 processing part to remove the dependency
on XML::Parser, applied a couple of patches, renamed a whole lot of methods
to make Pod::Coverage happy, and changed the docs.
.PP
The article eXtending \s-1XML\s0 XPath, http://www.xmltwig.com/article/extending_xml_xpath/
should give authors who want to use this module enough background to do so.
.PP
Otherwise, my email is below ;\-\-)
.PP
\&\fB\s-1WARNING\s0\fR: while the underlying code is rather solid, this module mostly lacks docs.
As they say, \*(L"patches welcome\*(R"...
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use XML::XPathEngine;
\&    
\&    my $tree= my_tree\->new( ...);
\&    my $xp = XML::XPathEngine\->new();
\&    
\&    my @nodeset = $xp\->find(\*(Aq/root/kid/grandkid[1]\*(Aq, $tree); # find all first grankids
\&
\&    package XML::MyTree;
\&
\&    # needs to provide DOM methods
.Ve
.SH "DETAILS"
.IX Header "DETAILS"
.SH "API"
.IX Header "API"
XML::XPathEngine will provide the following methods:
.SS "new"
.IX Subsection "new"
.ie n .SS "findnodes ($path, $context)"
.el .SS "findnodes ($path, \f(CW$context\fP)"
.IX Subsection "findnodes ($path, $context)"
Returns a list of nodes found by \f(CW$path\fR, optionally in context \f(CW$context\fR. 
In scalar context returns an XML::XPathEngine::NodeSet object.
.ie n .SS "findnodes_as_string ($path, $context)"
.el .SS "findnodes_as_string ($path, \f(CW$context\fP)"
.IX Subsection "findnodes_as_string ($path, $context)"
Returns the nodes found as a single string. The result is 
not guaranteed to be valid \s-1XML\s0 though (it could for example be just text
if the query returns attribute values).
.ie n .SS "findnodes_as_strings ($path, $context)"
.el .SS "findnodes_as_strings ($path, \f(CW$context\fP)"
.IX Subsection "findnodes_as_strings ($path, $context)"
Returns the nodes found as a list of strings, one per node found.
.ie n .SS "findvalue ($path, $context)"
.el .SS "findvalue ($path, \f(CW$context\fP)"
.IX Subsection "findvalue ($path, $context)"
Returns the result as a string (the concatenation of the values of the
result nodes).
.ie n .SS "findvalues($path, $context)"
.el .SS "findvalues($path, \f(CW$context\fP)"
.IX Subsection "findvalues($path, $context)"
Returns the values of the result nodes as a list of strings.
.ie n .SS "exists ($path, $context)"
.el .SS "exists ($path, \f(CW$context\fP)"
.IX Subsection "exists ($path, $context)"
Returns true if the given path exists.
.ie n .SS "matches($node, $path, $context)"
.el .SS "matches($node, \f(CW$path\fP, \f(CW$context\fP)"
.IX Subsection "matches($node, $path, $context)"
Returns true if the node matches the path.
.ie n .SS "find ($path, $context)"
.el .SS "find ($path, \f(CW$context\fP)"
.IX Subsection "find ($path, $context)"
The find function takes an XPath expression (a string) and returns either a
XML::XPathEngine::NodeSet object containing the nodes it found (or empty if
no nodes matched the path), or one of XML::XPathEngine::Literal (a string),
XML::XPathEngine::Number, or XML::XPathEngine::Boolean. It should always return 
something \- and you can use \->\fIisa()\fR to find out what it returned. If you
need to check how many nodes it found you should check \f(CW$nodeset\fR\->size.
See XML::XPathEngine::NodeSet.
.SS "getNodeText ($path)"
.IX Subsection "getNodeText ($path)"
Returns the text string for a particular node. Returns a string,
or undef if the node doesn't exist.
.ie n .SS "set_namespace ($prefix, $uri)"
.el .SS "set_namespace ($prefix, \f(CW$uri\fP)"
.IX Subsection "set_namespace ($prefix, $uri)"
Sets the namespace prefix mapping to the uri.
.PP
Normally in XML::XPathEngine the prefixes in XPath node tests take their
context from the current node. This means that foo:bar will always
match an element <foo:bar> regardless of the namespace that the prefix
foo is mapped to (which might even change within the document, resulting
in unexpected results). In order to make prefixes in XPath node tests
actually map to a real \s-1URI,\s0 you need to enable that via a call
to the set_namespace method of your XML::XPathEngine object.
.SS "clear_namespaces ()"
.IX Subsection "clear_namespaces ()"
Clears all previously set namespace mappings.
.ie n .SS "get_namespace ($prefix, $node)"
.el .SS "get_namespace ($prefix, \f(CW$node\fP)"
.IX Subsection "get_namespace ($prefix, $node)"
Returns the uri associated to the prefix for the node (mostly for internal usage)
.SS "set_strict_namespaces ($strict)"
.IX Subsection "set_strict_namespaces ($strict)"
By default, for historical as well as convenience reasons, XML::XPathEngine
has a slightly non-standard way of dealing with the default namespace.
.PP
If you search for \f(CW\*(C`//tag\*(C'\fR it will return elements \f(CW\*(C`tag\*(C'\fR. As far as I understand it,
if the document has a default namespace, this should not return anything.
You would have to first do a \f(CW\*(C`set_namespace\*(C'\fR, and then search using the namespace.
.PP
Passing a true value to \f(CW\*(C`set_strict_namespaces\*(C'\fR will activate this behaviour, passing a
false value will return it to its default behaviour.
.ie n .SS "set_var ($var. $val)"
.el .SS "set_var ($var. \f(CW$val\fP)"
.IX Subsection "set_var ($var. $val)"
Sets an XPath variable (that can be used in queries as \f(CW$var\fR)
.SS "get_var ($var)"
.IX Subsection "get_var ($var)"
Returns the value of the XPath variable (mostly for internal usage)
.ie n .SS "$XML::XPathEngine::Namespaces"
.el .SS "\f(CW$XML::XPathEngine::Namespaces\fP"
.IX Subsection "$XML::XPathEngine::Namespaces"
Set this to 0 if you \fIdon't\fR want namespace processing to occur. This
will make everything a little (tiny) bit faster, but you'll suffer for it,
probably.
.SH "Node Object Model"
.IX Header "Node Object Model"
Nodes need to provide the same \s-1API\s0 as nodes in XML::XPath (at least the access 
\&\s-1API,\s0 not the tree manipulation one).
.SH "Example"
.IX Header "Example"
Please see the test files in t/ for examples on how to use XPath.
.SH "XPath extension"
.IX Header "XPath extension"
The module supports the XPath recommendation to the same extend as XML::XPath 
(that is, rather completely).
.PP
It includes a perl-specific extension: direct support for regular expressions.
.PP
You can use the usual (in Perl!) \f(CW\*(C`=~\*(C'\fR and \f(CW\*(C`!~\*(C'\fR operators. Regular expressions 
are / delimited (no other delimiter is accepted, \e inside regexp must be 
backslashed), the \f(CW\*(C`imsx\*(C'\fR modifiers can be used.
.PP
.Vb 2
\&  $xp\->findnodes( \*(Aq//@att[.=~ /^v.$/]\*(Aq); # returns the list of attributes att
\&                                         # whose value matches ^v.$
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
XML::XPath
.PP
HTML::TreeBuilder::XPath, XML::Twig::XPath for examples of using this module
.PP
Tree::XPathEngine for a similar module for non-XML trees.
.PP
<http://www.xmltwig.com/article/extending_xml_xpath/> for background 
information. The last section of the article summarizes how to reuse XML::XPath.
As XML::XPathEngine offers the same \s-1API\s0 it should help you
.SH "AUTHOR"
.IX Header "AUTHOR"
Michel Rodriguez, \f(CW\*(C`<mirod@cpan.org>\*(C'\fR
Most code comes directly from XML::XPath, by Matt Sergeant.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-tree\-xpathengine@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML\-XPathEngine>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
XML::XPath Copyright 2000 AxKit.com Ltd.
Copyright 2006 Michel Rodriguez, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
