{ "content": [ { "type": "text", "text": "# XML::XPathEngine (perldoc)\n\n**Summary:** XML::XPathEngine - a re-usable XPath engine for DOM-like trees\n\n**Synopsis:** use XML::XPathEngine;\nmy $tree= mytree->new( ...);\nmy $xp = XML::XPathEngine->new();\nmy @nodeset = $xp->find('/root/kid/grandkid[1]', $tree); # find all first grankids\npackage XML::MyTree;\n# needs to provide DOM methods\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **DESCRIPTION** (24 lines)\n- **SYNOPSIS** (11 lines)\n- **DETAILS** (1 lines)\n- **API** (85 lines)\n- **Node Object Model** (3 lines)\n- **Example** (16 lines)\n- **SEE ALSO** (11 lines)\n- **AUTHOR** (3 lines)\n- **BUGS** (6 lines)\n- **ACKNOWLEDGEMENTS** (7 lines)\n\n## Full Content\n\n### NAME\n\nXML::XPathEngine - a re-usable XPath engine for DOM-like trees\n\n### DESCRIPTION\n\nThis module provides an XPath engine, that can be re-used by other\nmodule/classes that implement trees.\n\nIn order to use the XPath engine, nodes in the user module need to mimic\nDOM nodes. The degree of similitude between the user tree and a DOM\ndictates how much of the XPath features can be used. A module\nimplementing all of the DOM should be able to use this module very\neasily (you might need to add the cmp method on nodes in order to get\nordered result sets).\n\nThis code is a more or less direct copy of the XML::XPath module by Matt\nSergeant. I only removed the XML processing part to remove the\ndependency on XML::Parser, applied a couple of patches, renamed a whole\nlot of methods to make Pod::Coverage happy, and changed the docs.\n\nThe article eXtending XML XPath,\nhttp://www.xmltwig.com/article/extendingxmlxpath/ should give authors\nwho want to use this module enough background to do so.\n\nOtherwise, my email is below ;--)\n\nWARNING: while the underlying code is rather solid, this module mostly\nlacks docs. As they say, \"patches welcome\"...\n\n### SYNOPSIS\n\nuse XML::XPathEngine;\n\nmy $tree= mytree->new( ...);\nmy $xp = XML::XPathEngine->new();\n\nmy @nodeset = $xp->find('/root/kid/grandkid[1]', $tree); # find all first grankids\n\npackage XML::MyTree;\n\n# needs to provide DOM methods\n\n### DETAILS\n\n### API\n\nXML::XPathEngine will provide the following methods:\n\nnew\nfindnodes ($path, $context)\nReturns a list of nodes found by $path, optionally in context $context.\nIn scalar context returns an XML::XPathEngine::NodeSet object.\n\nfindnodesasstring ($path, $context)\nReturns the nodes found as a single string. The result is not guaranteed\nto be valid XML though (it could for example be just text if the query\nreturns attribute values).\n\nfindnodesasstrings ($path, $context)\nReturns the nodes found as a list of strings, one per node found.\n\nfindvalue ($path, $context)\nReturns the result as a string (the concatenation of the values of the\nresult nodes).\n\nfindvalues($path, $context)\nReturns the values of the result nodes as a list of strings.\n\nexists ($path, $context)\nReturns true if the given path exists.\n\nmatches($node, $path, $context)\nReturns true if the node matches the path.\n\nfind ($path, $context)\nThe find function takes an XPath expression (a string) and returns\neither a XML::XPathEngine::NodeSet object containing the nodes it found\n(or empty if no nodes matched the path), or one of\nXML::XPathEngine::Literal (a string), XML::XPathEngine::Number, or\nXML::XPathEngine::Boolean. It should always return something - and you\ncan use ->isa() to find out what it returned. If you need to check how\nmany nodes it found you should check $nodeset->size. See\nXML::XPathEngine::NodeSet.\n\ngetNodeText ($path)\nReturns the text string for a particular node. Returns a string, or\nundef if the node doesn't exist.\n\nsetnamespace ($prefix, $uri)\nSets the namespace prefix mapping to the uri.\n\nNormally in XML::XPathEngine the prefixes in XPath node tests take their\ncontext from the current node. This means that foo:bar will always match\nan element regardless of the namespace that the prefix foo is\nmapped to (which might even change within the document, resulting in\nunexpected results). In order to make prefixes in XPath node tests\nactually map to a real URI, you need to enable that via a call to the\nsetnamespace method of your XML::XPathEngine object.\n\nclearnamespaces ()\nClears all previously set namespace mappings.\n\ngetnamespace ($prefix, $node)\nReturns the uri associated to the prefix for the node (mostly for\ninternal usage)\n\nsetstrictnamespaces ($strict)\nBy default, for historical as well as convenience reasons,\nXML::XPathEngine has a slightly non-standard way of dealing with the\ndefault namespace.\n\nIf you search for \"//tag\" it will return elements \"tag\". As far as I\nunderstand it, if the document has a default namespace, this should not\nreturn anything. You would have to first do a \"setnamespace\", and then\nsearch using the namespace.\n\nPassing a true value to \"setstrictnamespaces\" will activate this\nbehaviour, passing a false value will return it to its default\nbehaviour.\n\nsetvar ($var. $val)\nSets an XPath variable (that can be used in queries as $var)\n\ngetvar ($var)\nReturns the value of the XPath variable (mostly for internal usage)\n\n$XML::XPathEngine::Namespaces\nSet this to 0 if you *don't* want namespace processing to occur. This\nwill make everything a little (tiny) bit faster, but you'll suffer for\nit, probably.\n\n### Node Object Model\n\nNodes need to provide the same API as nodes in XML::XPath (at least the\naccess API, not the tree manipulation one).\n\n### Example\n\nPlease see the test files in t/ for examples on how to use XPath.\n\nXPath extension\nThe module supports the XPath recommendation to the same extend as\nXML::XPath (that is, rather completely).\n\nIt includes a perl-specific extension: direct support for regular\nexpressions.\n\nYou can use the usual (in Perl!) \"=~\" and \"!~\" operators. Regular\nexpressions are / delimited (no other delimiter is accepted, \\ inside\nregexp must be backslashed), the \"imsx\" modifiers can be used.\n\n$xp->findnodes( '//@att[.=~ /^v.$/]'); # returns the list of attributes att\n# whose value matches ^v.$\n\n### SEE ALSO\n\nXML::XPath\n\nHTML::TreeBuilder::XPath, XML::Twig::XPath for examples of using this\nmodule\n\nTree::XPathEngine for a similar module for non-XML trees.\n\n for background\ninformation. The last section of the article summarizes how to reuse\nXML::XPath. As XML::XPathEngine offers the same API it should help you\n\n### AUTHOR\n\nMichel Rodriguez, \"\" Most code comes directly from\nXML::XPath, by Matt Sergeant.\n\n### BUGS\n\nPlease report any bugs or feature requests to\n\"bug-tree-xpathengine@rt.cpan.org\", or through the web interface at\n. I will\nbe notified, and then you'll automatically be notified of progress on\nyour bug as I make changes.\n\n### ACKNOWLEDGEMENTS\n\nCOPYRIGHT & LICENSE\nXML::XPath Copyright 2000 AxKit.com Ltd. Copyright 2006 Michel\nRodriguez, All Rights Reserved.\n\nThis program is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n\n" } ], "structuredContent": { "command": "XML::XPathEngine", "section": "", "mode": "perldoc", "summary": "XML::XPathEngine - a re-usable XPath engine for DOM-like trees", "synopsis": "use XML::XPathEngine;\nmy $tree= mytree->new( ...);\nmy $xp = XML::XPathEngine->new();\nmy @nodeset = $xp->find('/root/kid/grandkid[1]', $tree); # find all first grankids\npackage XML::MyTree;\n# needs to provide DOM methods", "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 24, "subsections": [] }, { "name": "SYNOPSIS", "lines": 11, "subsections": [] }, { "name": "DETAILS", "lines": 1, "subsections": [] }, { "name": "API", "lines": 85, "subsections": [] }, { "name": "Node Object Model", "lines": 3, "subsections": [] }, { "name": "Example", "lines": 16, "subsections": [] }, { "name": "SEE ALSO", "lines": 11, "subsections": [] }, { "name": "AUTHOR", "lines": 3, "subsections": [] }, { "name": "BUGS", "lines": 6, "subsections": [] }, { "name": "ACKNOWLEDGEMENTS", "lines": 7, "subsections": [] } ] } }