XML::XPathEngine(3)

📦
version 0.14 · 7 versions
, in opensuse-leap 16.0

💖 XML::XPathEngine(3) 💖

okay bestie, welcome to the XML::XPathEngine(3) page from the User Contributed Perl Documentation crew 🫶. This is the re-usable XPath engine one, and yes, we’re getting into all of it — every flag, method, warning, and little chaotic detail included 💅.

🌸 NAME 🌸

XML::XPathEngine — a re-usable XPath engine for DOM-like trees ✨

🦋 DESCRIPTION 🦋

This module gives you an XPath engine that other modules/classes implementing trees can re-use. To use it, nodes in your module need to mimick DOM nodes. The closer your tree is to a DOM, the more XPath features you can use — a module implementing all of the DOM should be able to use this module very easily, though you might need to add the cmp method on nodes to get ordered result sets 👑

This code is more or less a direct copy of the XML::XPath module by Matt Sergeant. The changes, fr fr:

  • the XML processing part was removed, so there’s no dependency on XML::Parser
  • a couple of patches were applied
  • a whole lot of methods were renamed to make Pod::Coverage happy
  • the docs were changed

The article eXtending XML XPath at http://www.xmltwig.com/article/extending_xml_xpath/ should give authors who want to use this module enough background to do so 🎀

Otherwise, my email is below ;--)

WARNING: while the underlying code is rather solid, this module mostly lacks docs. As they say, “patches welcome”… 😭

🎀 SYNOPSIS 🎀

use XML::XPathEngine;

my $tree= my_tree->new( ...);
my $xp = XML::XPathEngine->new();

my @nodeset = $xp->find('/root/kid/grandkid[1]', $tree); # find all first grankids

package XML::MyTree;

# needs to provide DOM methods

🌈 DETAILS 🌈

💅 API 💅

XML::XPathEngine will provide the following methods, bestie:

  • new — it’s listed as an API method; the original page does not add a description here 🎀
  • findnodes ($path, $context) — returns a list of nodes found by $path, optionally in context $context. In scalar context it returns an XML::XPathEngine::NodeSet object ✨
  • findnodes_as_string ($path, $context) — returns the nodes found as a single string. The result is not guaranteed to be valid XML though; it could, for example, be just text if the query returns attribute values 🦋
  • findnodes_as_strings ($path, $context) — returns the nodes found as a list of strings, one per node found 💖
  • findvalue ($path, $context) — returns the result as a string, aka the concatenation of the values of the result nodes 🌸
  • findvalues($path, $context) — returns the values of the result nodes as a list of strings 💜
  • exists ($path, $context) — returns true if the given path exists 👑
  • matches($node, $path, $context) — returns true if the node matches the path 🔥
  • find ($path, $context) — takes an XPath expression (a string) and returns either an 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 ->isa() to find out what it returned. If you need to check how many nodes it found, check $nodeset->size. See XML::XPathEngine::NodeSet 💅
  • getNodeText ($path) — returns the text string for a particular node. Returns a string, or undef if the node doesn’t exist 😭
  • set_namespace ($prefix, $uri) — sets the namespace prefix mapping to the uri. Normally in XML::XPathEngine the prefixes in XPath node tests take their context from the current node. This means 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 🙈. To make prefixes in XPath node tests actually map to a real URI, you need to enable that via a call to the set_namespace method of your XML::XPathEngine object ✨
  • clear_namespaces () — clears all previously set namespace mappings 🧚
  • get_namespace ($prefix, $node) — returns the uri associated to the prefix for the node, mostly for internal usage 🎀
  • 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. If you search for "//tag" it will return elements "tag". 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 "set_namespace", and then search using the namespace. Passing a true value to "set_strict_namespaces" will activate this behaviour; passing a false value will return it to its default behaviour 👑
  • set_var ($var. $val) — sets an XPath variable that can be used in queries as $var 🌟
  • get_var ($var) — returns the value of the XPath variable, mostly for internal usage 💫
  • $XML::XPathEngine::Namespaces — set this to 0 if you don’t want namespace processing to occur. This will make everything a little (tiny) bit faster, but you’ll suffer for it, probably 💀

🌿 Node Object Model 🌿

Nodes need to provide the same API as nodes in XML::XPath — at least the access API, not the tree manipulation one, bestie 🫶

🍓 Example 🍓

Please see the test files in t/ for examples on how to use XPath ✨

🧚 XPath extension 🧚

The module supports the XPath recommendation to the same extent as XML::XPath — that is, rather completely 👑

It includes a perl-specific extension: direct support for regular expressions 🔥

You can use the usual (in Perl!) =~ and !~ operators. Regular expressions are / delimited — no other delimiter is accepted, \ inside regexp must be backslashed — and the imsx modifiers can be used 💅

  $xp->findnodes( '//@att[.=~ /^v.$/]'); # returns the list of attributes att
                                         # whose value matches ^v.$

🌈 SEE ALSO 🌈

  • XML::XPath 💖
  • HTML::TreeBuilder::XPath, XML::Twig::XPath for exemples of using this module 🌸
  • Tree::XPathEngine for a similar module for non-XML trees 🦋
  • <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 API, it should help you 🎀

👑 AUTHOR 👑

Michel Rodriguez, "<mirod@cpan.org>" — most code comes directly from XML::XPath, by Matt Sergeant 🌟

💀 BUGS 💀

Please report any bugs or feature requests to "bug-tree-xpathengine@rt.cpan.org", 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 🫶

🫶 ACKNOWLEDGEMENTS 🫶

This section is literally empty in the original, bestie — nothing listed here 💀

XML::XPath Copyright 2000 AxKit.com Ltd. Copyright 2006 Michel Rodriguez, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself 💖

k byeee — this was the XML::XPathEngine(3) page from perl v5.42.0, dated 2013-06-04, and yes she ate 💅✨

📦 where this page comes from