NAME

XML::Grove::Iter - add tree iteration methods to XML objects

SYNOPSIS

use XML::Grove::Iter;

$iter = $xml_object->iter;

$iter2 = $iter->parent;
$iter2 = $iter->next;
$iter2 = $iter->previous;

$iter2 = $element_iter->first_child;
$iter2 = $element_iter->last_child;
$iter2 = $element_iter->attr_first ($attr);
$iter2 = $element_iter->attr_last ($attr);

$obj = $iter->delegate;
$root = $iter->root;
@path = $iter->rootpath;

$bool = $iter->is_iter;
$bool = $iter->is_same ($obj);
$bool = $iter->at_last;
$bool = $iter->at_first;

DESCRIPTION

XML::Grove::Iter is a proxy-based tree iterator. ``Proxy based'' means that the iterator ``stands in'' for the real object and is used as you would normally use the real object. The iterator handles moving around the tree and forwards all other methods to the real object.

`parent' returns the parent iterator of this iterator, or `undef' if this is the root iterator. `next' and `previous' return the iterator of the next object or the previous object, respectively, in the parent's content (the sibling objects), or `undef' if there is no next or previous sibling.

`first_child' and `last_child' return the iterator of the first child or the last child of the contents of this element or document. `attr_first' and `attr_last' return the iterator of the first child or last child of the named attribute. These all return `undef' if the contents are empty.

`delegate' returns the object that this iterator stands-in for, ``the delegate''.

`root' returns the iterator of the top-most object of the sub-tree being iterated. Note that this may not be the root of the document tree if the first iterator was created using a nested object.

`rootpath' returns a list of the parent iterators between and including the root and this iterator.

`is_iter' returns true if this object is an iterator. Ordinary XML objects have been extended with an `is_iter' method that returns false.

`is_same' returns true if `$obj' is this iterator's delegate, or if `$obj' is an iterator that points to the same delegate.

`at_last' and `at_first' return true if calling `next' or `previous', respectively, would return `undef'. Or in other words, they return true if this iterator is at the end or the beginning of the parent element's content.

AUTHOR

Ken MacLeod, ken@bitsko.slc.ut.us

SEE ALSO

perl(1), XML::Parser(3), XML::Parser::Grove(3).

Extensible Markup Language (XML) <http://www.w3c.org/XML>