/ 
XML-TreePuller-0.0.3_01
River stage one • 1 direct dependent • 1 total dependent
/ XML::TreePuller

NAME

XML::TreePuller - pull interface to work with XML document fragments

SYNOPSIS

use XML::TreePuller;

$pull = XML::TreePuller->new(location => '/what/ever/filename.xml');
$pull = XML::TreePuller->new(location => 'http://urls.work.too/data.xml');
$pull = XML::TreePuller->new(IO => \*FH);
$pull = XML::TreePuller->new(string => '<xml/>');

$pull->reader;

$pull->config('/xml', 'short');
$pull->config('/xml', 'subtree');

while(defined($element = $pull->next)) { }

$element->name;
$element->text;
$element->attribute('attribute_name');
$element->get_elements('element/path');

ABOUT

This module implements a tree oriented XML pull processor using a combination of XML::LibXML::Reader and an object-oriented interface around the output of XML::CompactTree. It provides a fast and convenient way to access the content of extremely large XML documents serially.

XML::TreePuller

METHODS

new

The constructor for this class returns an instance of itself; all arguments are passed straight on to XML::LibXML::Reader when it is constructed. See the documentation for a full specification of what you can use but for quick reference:

new(location => '/what/ever/filename.xml');
new(location => 'http://urls.work.too/data.xml');
new(string => $xml_data);
new(IO => \*FH);
config

This method allows you to control the configuration of the processing engine. You specify a path to an XML element and an instruction: short or subtree. The combination of the current path of the XML document in the reader and the instruction to use will generate instances of XML::TreePuller::Element available from the "next" method.

config('/path/to/element' => 'short');

When the path of the current XML element matches the path specified the "next" method will return an instance of XML::TreePuller::Element that holds any attributes and will contain textual data up to the start of another element; there will be no child elements in this element.

config('/ditto' => 'subtree');

When the path of the current XML element matches the path specified the "next" method will return an instance of XML::TreePuller::Element that holds the attributes for the element and all of the element textual data and child elements.

next

This method is the iterator for the processing system. Each time an instruction is matched it will return an instance of XML::TreePuller::Element. When called in scalar context returns a reference to the next available element or undef when no more data is available. When called in list context it returns a two item list with the first item being the path to the node that was matched and the second item being the next available element; returns an empty list when there is no more data to be processed.

reader

Returns the instance of XML::LibXML::Reader that we are using to parse the XML document. You can move the cursor of the reader if you want.

XML::TreePuller::Element

This class is how you access the data from XML::TreePuller.

METHODS

name

Returns the name of the element as a string

text

Returns the text stored in the element as a string; returns an empty string if there is no text

attribute

If called with out any arguments returns a hash reference containing the attribute names as keys and the attribute values as the data. If called with an argument returns the value for the attribute by that name or undef if there is no attribute by that name.

get_elements

Searches this element for any child elements as matched by the path supplied as an argument. The path is of the format 'node1/node2/node3' where each node name is seperated by a forward slash and there is no trailing or leading forwardslashes.

If called in scalar context returns the first element that matches the path; if called in array context returns a list of all elements that matched.

EXAMPLE

use strict;
use warnings;

use XML::TreePuller;

sub gen_xml {
  	return <<EOF
  	
<wiki version="0.3">

<!-- schema says that there is always 1 siteinfo and zero or more page 
  elements follow -->
<siteinfo>
  <sitename>ExamplePedia</sitename>
  <url>http://example.pedia/</url>
  <namespaces>
    <namespace key="-1">Special</namespace>
    <namespace key="0" />
    <namespace key="1">Talk</namespace>
  </namespaces>
</siteinfo>

<page>
  <title>A good article</title>
  <text>Some good content</text>
</page>    

<page>
  <title>A bad article</title>
  <text>Some bad content</text>
</page>

</wiki>
  	  	
EOF
}

sub element_example {
	my $xml = XML::TreePuller->new(string => gen_xml());
	
	print "Printing namespace names using configuration style:\n";
	
	$xml->config('/wiki/siteinfo/namespaces/namespace' => 'short');
	
	while(defined(my $element = $xml->next)) {
		print $element->attribute('key'), ": ", $element->text, 
			"\n";
	}
	
	print "End of namespace names\n";
}

sub subtree_example {
	my $xml = XML::TreePuller->new(string => gen_xml());
	
	print "Printing titles using a subtree:\n";
	
	$xml->config('/wiki/page' => 'subtree');

	while(defined(my $element = $xml->next)) {
		print "Title: ", $element->get_elements('title')->text, 
			"\n";
	}	
	
	print "End of titles\n";
}

sub path_example {
	my $xml = XML::TreePuller->new(string => gen_xml());
	
	print "Printing path example:\n";
	
	$xml->config('/wiki/siteinfo', 'subtree');
	$xml->config('/wiki/page/title', 'short');
	
	while(my ($matched_path, $element) = $xml->next) {
		print "Path: $matched_path\n";
	}
	
	print "End path example\n";
}

element_example(); print "\n";
subtree_example(); print "\n";
path_example(); print "\n";
  
__END__

Output:

Printing namespace names using configuration style:
-1: Special
0: 
1: Talk
End of namespace names

Printing titles using a subtree:
Title: A good article
Title: A bad article
End of titles

Printing path example:
Path: /wiki/siteinfo
Path: /wiki/page/title
Path: /wiki/page/title
End path example