Refactored Sector:: out from under Engine:: and into its own area

[dbsrgits/DBM-Deep.git] / lib / DBM / Deep / Iterator.pm

diff --git a/lib/DBM/Deep/Iterator.pm b/lib/DBM/Deep/Iterator.pm
index 6de0e05..7c28b6f 100644 (file)
--- a/lib/DBM/Deep/Iterator.pm
+++ b/lib/DBM/Deep/Iterator.pm
@@ -5,10 +5,38 @@ use 5.006_000;
 use strict;
 use warnings FATAL => 'all';
 
-use Scalar::Util ();
+use DBM::Deep::Iterator::BucketList ();
+use DBM::Deep::Iterator::Index ();
 
-use DBM::Deep::Iterator::Index;
-use DBM::Deep::Iterator::BucketList;
+=head1 NAME
+
+DBM::Deep::Iterator
+
+=head1 PURPOSE
+
+This is an internal-use-only object for L<DBM::Deep/>. It is the iterator
+for FIRSTKEY() and NEXTKEY().
+
+=head1 OVERVIEW
+
+This object 
+
+=head1 METHODS
+
+=head2 new(\%params)
+
+The constructor takes a hashref of params. The hashref is assumed to have the
+following elements:
+
+=over 4
+
+=item * engine (of type L<DBM::Deep::Engine/>
+
+=item * base_offset (the base_offset of the invoking DBM::Deep object)
+
+=back
+
+=cut
 
 sub new {
     my $class = shift;
@@ -25,22 +53,41 @@ sub new {
     return $self;
 }
 
+=head2 reset()
+
+This method takes no arguments.
+
+It will reset the iterator so that it will start from the beginning again.
+
+This method returns nothing.
+
+=cut
+
 sub reset { $_[0]{breadcrumbs} = [] }
 
+=head2 get_sector_iterator( $loc )
+
+This takes a location. It will load the sector for $loc, then instantiate the right
+iteartor type for it.
+
+This returns the sector iterator.
+
+=cut
+
 sub get_sector_iterator {
     my $self = shift;
     my ($loc) = @_;
 
-    my $sector = $self->{engine}->_load_sector( $loc )
+    my $sector = DBM::Deep::Sector::File->load( $self->{engine}, $loc )
         or return;
 
-    if ( $sector->isa( 'DBM::Deep::Engine::Sector::Index' ) ) {
+    if ( $sector->isa( 'DBM::Deep::Sector::File::Index' ) ) {
         return DBM::Deep::Iterator::Index->new({
             iterator => $self,
             sector   => $sector,
         });
     }
-    elsif ( $sector->isa( 'DBM::Deep::Engine::Sector::BucketList' ) ) {
+    elsif ( $sector->isa( 'DBM::Deep::Sector::File::BucketList' ) ) {
         return DBM::Deep::Iterator::BucketList->new({
             iterator => $self,
             sector   => $sector,
@@ -50,6 +97,10 @@ sub get_sector_iterator {
     DBM::Deep->_throw_error( "get_sector_iterator(): Why did $loc make a $sector?" );
 }
 
+=head2 get_next_key( $obj )
+
+=cut
+
 sub get_next_key {
     my $self = shift;
     my ($obj) = @_;
@@ -59,8 +110,8 @@ sub get_next_key {
 
     unless ( @$crumbs ) {
         # This will be a Reference sector
-        my $sector = $e->_load_sector( $self->{base_offset} )
-            # If no sector is found, thist must have been deleted from under us.
+        my $sector = DBM::Deep::Sector::File->load( $e, $self->{base_offset} )
+            # If no sector is found, this must have been deleted from under us.
             or return;
 
         if ( $sector->staleness != $obj->_staleness ) {