{ "content": [ { "type": "text", "text": "# XML::XPathEngine (perldoc)\n\n## NAME\n\nXML::XPathEngine - a re-usable XPath engine for DOM-like trees\n\n## SYNOPSIS\n\nuse 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## DESCRIPTION\n\nThis module provides an XPath engine, that can be re-used by other module/classes that implement\ntrees.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **SYNOPSIS**\n- **DETAILS**\n- **API**\n- **Node Object Model**\n- **Example**\n- **SEE ALSO**\n- **AUTHOR**\n- **BUGS**\n- **ACKNOWLEDGEMENTS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\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", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 20, "subsections": [] }, { "name": "SYNOPSIS", "lines": 11, "subsections": [] }, { "name": "DETAILS", "lines": 1, "subsections": [] }, { "name": "API", "lines": 75, "subsections": [] }, { "name": "Node Object Model", "lines": 3, "subsections": [] }, { "name": "Example", "lines": 15, "subsections": [] }, { "name": "SEE ALSO", "lines": 10, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "BUGS", "lines": 4, "subsections": [] }, { "name": "ACKNOWLEDGEMENTS", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "XML::XPathEngine - a re-usable XPath engine for DOM-like trees\n", "subsections": [] }, "DESCRIPTION": { "content": "This module provides an XPath engine, that can be re-used by other module/classes that implement\ntrees.\n\nIn order to use the XPath engine, nodes in the user module need to mimic DOM nodes. The degree\nof similitude between the user tree and a DOM dictates how much of the XPath features can be\nused. A module implementing all of the DOM should be able to use this module very easily (you\nmight need to add the cmp method on nodes in order to get ordered result sets).\n\nThis code is a more or less direct copy of the XML::XPath module by Matt Sergeant. I only\nremoved the XML processing part to remove the dependency on XML::Parser, applied a couple of\npatches, renamed a whole lot of methods to make Pod::Coverage happy, and changed the docs.\n\nThe article eXtending XML XPath, http://www.xmltwig.com/article/extendingxmlxpath/ should give\nauthors who 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 lacks docs. As they say,\n\"patches welcome\"...\n", "subsections": [] }, "SYNOPSIS": { "content": "use 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", "subsections": [] }, "DETAILS": { "content": "", "subsections": [] }, "API": { "content": "XML::XPathEngine will provide the following methods:\n\nnew\nfindnodes ($path, $context)\nReturns a list of nodes found by $path, optionally in context $context. In scalar context\nreturns an XML::XPathEngine::NodeSet object.\n\nfindnodesasstring ($path, $context)\nReturns the nodes found as a single string. The result is not guaranteed to be valid XML though\n(it could for example be just text if the query returns 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 result 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 either a\nXML::XPathEngine::NodeSet object containing the nodes it found (or empty if no nodes matched the\npath), or one of XML::XPathEngine::Literal (a string), XML::XPathEngine::Number, or\nXML::XPathEngine::Boolean. It should always return something - and you can use ->isa() to find\nout what it returned. If you need to check how many nodes it found you should check\n$nodeset->size. See XML::XPathEngine::NodeSet.\n\ngetNodeText ($path)\nReturns the text string for a particular node. Returns a string, or undef if the node doesn't\nexist.\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 context from the\ncurrent node. This means that foo:bar will always match an element regardless of the\nnamespace that the prefix foo is mapped to (which might even change within the document,\nresulting in unexpected results). In order to make prefixes in XPath node tests actually map to\na real URI, you need to enable that via a call to the setnamespace method of your\nXML::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 internal usage)\n\nsetstrictnamespaces ($strict)\nBy default, for historical as well as convenience reasons, XML::XPathEngine has a slightly\nnon-standard way of dealing with the default namespace.\n\nIf you search for \"//tag\" it will return elements \"tag\". As far as I understand it, if the\ndocument has a default namespace, this should not return anything. You would have to first do a\n\"setnamespace\", and then search using the namespace.\n\nPassing a true value to \"setstrictnamespaces\" will activate this behaviour, passing a false\nvalue will return it to its default behaviour.\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 will make everything a\nlittle (tiny) bit faster, but you'll suffer for it, probably.\n", "subsections": [] }, "Node Object Model": { "content": "Nodes need to provide the same API as nodes in XML::XPath (at least the access API, not the tree\nmanipulation one).\n", "subsections": [] }, "Example": { "content": "Please 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 XML::XPath (that is, rather\ncompletely).\n\nIt includes a perl-specific extension: direct support for regular expressions.\n\nYou can use the usual (in Perl!) \"=~\" and \"!~\" operators. Regular expressions are / delimited\n(no other delimiter is accepted, \\ inside regexp must be backslashed), the \"imsx\" modifiers can\nbe used.\n\n$xp->findnodes( '//@att[.=~ /^v.$/]'); # returns the list of attributes att\n# whose value matches ^v.$\n", "subsections": [] }, "SEE ALSO": { "content": "XML::XPath\n\nHTML::TreeBuilder::XPath, XML::Twig::XPath for examples of using this module\n\nTree::XPathEngine for a similar module for non-XML trees.\n\n for background information. The last\nsection of the article summarizes how to reuse XML::XPath. As XML::XPathEngine offers the same\nAPI it should help you\n", "subsections": [] }, "AUTHOR": { "content": "Michel Rodriguez, \"\" Most code comes directly from XML::XPath, by Matt Sergeant.\n", "subsections": [] }, "BUGS": { "content": "Please report any bugs or feature requests to \"bug-tree-xpathengine@rt.cpan.org\", or through the\nweb interface at . I will be\nnotified, and then you'll automatically be notified of progress on your bug as I make changes.\n", "subsections": [] }, "ACKNOWLEDGEMENTS": { "content": "COPYRIGHT & LICENSE\nXML::XPath Copyright 2000 AxKit.com Ltd. Copyright 2006 Michel Rodriguez, All Rights Reserved.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] } } } }