From a2d12bc84fb2af87dd1c0c6e5bc854554902cd67 Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Sun, 26 Jan 2003 19:35:03 +0000 Subject: Imported from /home/lorry/working-area/delta_perl-xml-xpath/XML-XPath-1.13.tar.gz. --- README | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..154e79f --- /dev/null +++ b/README @@ -0,0 +1,193 @@ +NAME + XML::XPath - a set of modules for parsing and evaluating XPath + statements + +DESCRIPTION + This module aims to comply exactly to the XPath specification at + http://www.w3.org/TR/xpath and yet allow extensions to be added + in the form of functions. Modules such as XSLT and XPointer may + need to do this as they support functionality beyond XPath. + +SYNOPSIS + use XML::XPath; + use XML::XPath::XMLParser; + + my $xp = XML::XPath->new(filename => 'test.xhtml'); + + my $nodeset = $xp->find('/html/body/p'); # find all paragraphs + + foreach my $node ($nodeset->get_nodelist) { + print "FOUND\n\n", + XML::XPath::XMLParser::as_string($node), + "\n\n"; + } + +DETAILS + There's an awful lot to all of this, so bear with it - if you + stick it out it should be worth it. Please get a good + understanding of XPath by reading the spec before asking me + questions. All of the classes and parts herein are named to be + synonimous with the names in the specification, so consult that + if you don't understand why I'm doing something in the code. + +API + The API of XML::XPath itself is extremely simple to allow you to + get going almost immediately. The deeper API's are more complex, + but you shouldn't have to touch most of that. + + new() + + This constructor follows the often seen named parameter method + call. Parameters you can use are: filename, parser, xml, ioref + and context. The filename parameter specifies an XML file to + parse. The xml parameter specifies a string to parse, and the + ioref parameter specifies an ioref to parse. The context option + allows you to specify a context node. The context node has to be + in the format of a node as specified in the + XML::XPath::XMLParser manpage. The 4 parameters filename, xml, + ioref and context are mutually exclusive - you should only + specify one (if you specify anything other than context, the + context node is the root of your document). The parser option + allows you to pass in an already prepared XML::Parser object, to + save you having to create more than one in your application (if, + for example, you're doing more than just XPath). + + my $xp = XML::XPath->new( context => $node ); + + It is very much recommended that you use only 1 XPath object + throughout the life of your application. This is because the + object (and it's sub-objects) maintain certain bits of state + information that will be useful (such as XPath variables) to + later calls to find(). It's also a good idea because you'll use + less memory this way. + + *nodeset* = find($path, [$context]) + + The find function takes an XPath expression (a string) and + returns either an XML::XPath::NodeSet object containing the + nodes it found (or empty if no nodes matched the path), or one + of XML::XPath::Literal (a string), XML::XPath::Number, or + XML::XPath::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 you should check $nodeset->size. + See the XML::XPath::NodeSet manpage. An optional second + parameter of a context node allows you to use this method + repeatedly, for example XSLT needs to do this. + + findnodes($path, [$context]) + + Returns a list of nodes found by $path, optionally in context + $context. In scalar context returns an XML::XPath::NodeSet + object. + + findnodes_as_string($path, [$context]) + + Returns the nodes found reproduced as XML. The result is not + guaranteed to be valid XML though. + + findvalue($path, [$context]) + + Returns either a `XML::XPath::Literal', a `XML::XPath::Boolean' + or a `XML::XPath::Number' object. If the path returns a NodeSet, + $nodeset->to_literal is called automatically for you (and thus a + `XML::XPath::Literal' is returned). Note that for each of the + objects stringification is overloaded, so you can just print the + value found, or manipulate it in the ways you would a normal + perl value (e.g. using regular expressions). + + matches($node, $path, [$context]) + + Returns true if the node matches the path (optionally in context + $context). + + set_namespace($prefix, $uri) + + Sets the namespace prefix mapping to the uri. + + Normally in XML::XPath the prefixes in XPath node tests take + their context from the current node. This means that foo:bar + will always match an element 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 URI, you need to enable that via a call to the + set_namespace method of your XML::XPath object. + + clear_namespaces() + + Clears all previously set namespace mappings. + + $XML::XPath::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 + See the XML::XPath::Node manpage, the XML::XPath::Node::Element + manpage, the XML::XPath::Node::Text manpage, the + XML::XPath::Node::Comment manpage, the + XML::XPath::Node::Attribute manpage, the + XML::XPath::Node::Namespace manpage, and the + XML::XPath::Node::PI manpage. + +On Garbage Collection + XPath nodes work in a special way that allows circular + references, and yet still lets Perl's reference counting garbage + collector to clean up the nodes after use. This should be + totally transparent to the user, with one caveat: If you free + your tree before letting go of a sub-tree, consider that playing + with fire and you may get burned. What does this mean to the + average user? Not much. Provided you don't free (or let go out + of scope) either the tree you passed to XML::XPath->new, or if + you didn't pass a tree, and passed a filename or IO-ref, then + provided you don't let the XML::XPath object go out of scope + before you let results of find() and its friends go out of + scope, then you'll be fine. Even if you do let the tree go out + of scope before results, you'll probably still be fine. The only + case where you may get stung is when the last part of your + path/query is either an ancestor or parent axis. In that case + the worst that will happen is you'll end up with a circular + reference that won't get cleared until interpreter destruction + time. You can get around that by explicitly calling $node- + >DESTROY on each of your result nodes, if you really need to do + that. + + Mail me direct if that's not clear. Note that it's not doom and + gloom. It's by no means perfect, but the worst that will happen + is a long running process could leak memory. Most long running + processes will therefore be able to explicitly be careful not to + free the tree (or XML::XPath object) before freeing results. + AxKit, an application that uses XML::XPath, does this and I + didn't have to make any changes to the code - it's already + sensible programming. + + If you *really* don't want all this to happen, then set the + variable $XML::XPath::SafeMode, and call $xp->cleanup() on the + XML::XPath object when you're finished, or $tree->dispose() if + you have a tree instead. + +Example + Please see the test files in t/ for examples on how to use + XPath. + +Support/Author + This module is copyright 2000 AxKit.com Ltd. This is free + software, and as such comes with NO WARRANTY. No dates are used + in this module. You may distribute this module under the terms + of either the Gnu GPL, or the Artistic License (the same terms + as Perl itself). + + For support, please subscribe to the Perl-XML mailing list at + the URL http://listserv.activestate.com/mailman/listinfo/perl- + xml + + Matt Sergeant, matt@sergeant.org + +SEE ALSO + the XML::XPath::Literal manpage, the XML::XPath::Boolean + manpage, the XML::XPath::Number manpage, the + XML::XPath::XMLParser manpage, the XML::XPath::NodeSet manpage, + the XML::XPath::PerlSAX manpage, the XML::XPath::Builder + manpage. + -- cgit v1.2.1