lib/DBM/Deep/Iterator.pm

   1 package DBM::Deep::Iterator;
   2
   3 use 5.006_000;
   4
   5 use strict;
   6 use warnings FATAL => 'all';
   7
   8 use DBM::Deep::Iterator::DBI ();
   9 use DBM::Deep::Iterator::File ();
  10
  11 =head1 NAME
  12
  13 DBM::Deep::Iterator
  14
  15 =head1 PURPOSE
  16
  17 This is an internal-use-only object for L<DBM::Deep/>. It is the iterator
  18 for FIRSTKEY() and NEXTKEY().
  19
  20 =head1 OVERVIEW
  21
  22 This object
  23
  24 =head1 METHODS
  25
  26 =head2 new(\%params)
  27
  28 The constructor takes a hashref of params. The hashref is assumed to have the
  29 following elements:
  30
  31 =over 4
  32
  33 =item * engine (of type L<DBM::Deep::Engine/>
  34
  35 =item * base_offset (the base_offset of the invoking DBM::Deep object)
  36
  37 =back
  38
  39 =cut
  40
  41 sub new {
  42     my $class = shift;
  43     my ($args) = @_;
  44
  45     my $self = bless {
  46         breadcrumbs => [],
  47         engine      => $args->{engine},
  48         base_offset => $args->{base_offset},
  49     }, $class;
  50
  51     Scalar::Util::weaken( $self->{engine} );
  52
  53     return $self;
  54 }
  55
  56 =head2 reset()
  57
  58 This method takes no arguments.
  59
  60 It will reset the iterator so that it will start from the beginning again.
  61
  62 This method returns nothing.
  63
  64 =cut
  65
  66 sub reset { $_[0]{breadcrumbs} = []; return }
  67
  68 =head2 get_sector_iterator( $loc )
  69
  70 This takes a location. It will load the sector for $loc, then instantiate the
  71 right iteartor type for it.
  72
  73 This returns the sector iterator.
  74
  75 =cut
  76
  77 sub get_sector_iterator { die "get_sector_iterator must be implemented in a child class" }
  78
  79 =head2 get_next_key( $obj )
  80
  81 =cut
  82
  83 sub get_next_key { die "get_next_key must be implemented in a child class" }
  84
  85 1;
  86 __END__