Anonymous avatar Anonymous committed 670930b

Modified Files:
lib/XML/LibXML/Iterator.pm
+ docs
- default iterator will work correctly

Comments (0)

Files changed (1)

lib/XML/LibXML/Iterator.pm

 
 sub first {
     my $self = shift;
+    if ( scalar @_ ) {
+        $self->{FIRST} = shift;
+    }
     $self->{CURRENT} = $self->{FIRST};
     $self->{INDEX}   = 0;
     return $self->current;
           and $self->{INDEX} <= 0;
 
         $node = $self->{CURRENT}->previousSibling;
-        if  ( not defined $node ) {
-            $node = $self->{CURRENT}->parentNode;
-        }
-        elsif ( $node->hasChildNodes ) {
+        return $self->{CURRENT}->parentNode unless defined $node;
+
+        while ( $node->hasChildNodes ) {
             $node = $node->lastChild;
         }
     }
         }
         else {
             $node = $self->{CURRENT}->nextSibling;
-            unless ( defined $node ) {
-                $node = $self->{CURRENT}->parentNode;
-                $node = $node->nextSibling if defined $node;
+            my $pnode = $self->{CURRENT}->parentNode;
+            while ( not defined $node ) {
+                last unless defined $pnode;
+                $node = $pnode->nextSibling;
+                $pnode = $pnode->parentNode unless defined $node;
             }
         }
     }
 
 =head1 NAME
 
-XML::LibXML::Iterator - Simple Tree Iteration Class for XML::LibXML
+XML::LibXML::Iterator - XML::LibXML's Simple Tree Iteration Class
 
 =head1 SYNOPSIS
 
 
 =head1 DESCRIPTION
 
-An iterator allows to operate on a document tree as it would be a
-linear sequence of nodes.
+XML::LibXML::Iterator is an iterator class for XML::LibXML parsed
+documents. This class allows to iterate the document tree as it were a
+linear data structure. It is possible to step back and forth between
+the nodes of the tree and do certain operations on that
+nodes. Different to XPath the nodes are not prefetched but will be
+calculated for each step. Therefore an iterator is sensible towards
+the current state of a document tree on each step, while XPath is only
+per query executed.
+
+=head2 What is an iterator?
+
+XML::LibXML offers by default a W3C DOM interface on the parsed XML
+documents. This tree has per definition four directions to be
+traversed: Up, down, foreward and backward. Therefore a tree can be
+considered two dimensional. Although a tree is still one more simple
+datastructure it is way to complex for some operations. So the
+XML::LibXML::Iterator class breaks the for operations down to only
+two: backward and forward. For some people this easier to understand
+than DOM or SAX as this follows more the way one actually reads an XML
+document.
+
+Therefore an iterator has three basic functions:
+
+=over 4
+
+=item * next()
+
+=item * current()
+
+=item * previous()
+
+=back
+
+That's it. With an iterator one does not have to decide when to dive
+into a subtree or find a parent. It is not even required to care about
+the boundaries of a certain level. The iterator will get the next node
+for you until there is no node left to handle.
+
+In short: An iterator will answer the question about what is next to
+do.
+
+=head2 How to use XML::LibXML::Iterator?
+
+XML::LibXML::Iterator requires a parsed document or at least a node to
+operate on. This node is passed to the iterator class and will be used
+as the B<first> node of the iteration. One can allways reset the
+iterator to the first node by using the first()-function.
+
+Once XML::LibXML::Iterator is initialized the tree can be traversed by
+using either next() or previous(). Both function will return a
+XML::LibXML::Node object if there is such object available.
+
+Since the current object in the iterator is always available via the
+current() function, the position of the iterator can be changed inside
+a method or function.
+
 
 =head2 Functions
 
 
 =item index()
 
-=item iterator_function($funcion_ref);
+=item iterator_function($funcion_ref)
 
-=item iterate($function_ref);
+=item iterate($function_ref)
 
 =back
 
+
 XML::LibXML::Iterator knows two types of callback. One is knows as the
 iterator function, the other is used by iterate(). The first function
 will be called for each call of next() or previous(). It is used to
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.