File Coverage

blib/lib/Rose/DB/Object/Iterator.pm
Criterion Covered Total %
statement 12 26 46.1
branch 0 6 0.0
condition n/a
subroutine 4 9 44.4
pod 3 3 100.0
total 19 44 43.1


line stmt bran cond sub pod time code
1             package Rose::DB::Object::Iterator;
2              
3 61     61   431 use strict;
  61         124  
  61         1811  
4              
5 61     61   306 use Carp();
  61         133  
  61         1126  
6              
7 61     61   742 use Rose::Object;
  61         289  
  61         5554  
8             our @ISA = qw(Rose::Object);
9              
10             our $VERSION = '0.759';
11              
12             use Rose::Object::MakeMethods::Generic
13             (
14 61         751 scalar =>
15             [
16             'error',
17             '_count',
18             '_next_code',
19             '_finish_code',
20             '_destroy_code',
21             ],
22              
23             'boolean' => 'active',
24 61     61   1080 );
  61         8946  
25              
26             sub next
27             {
28 0     0 1   my($self) = shift;
29 0           my $ret = $self->_next_code->($self, @_);
30 0 0         $self->active(0) unless($ret);
31 0           return $ret;
32             }
33              
34             sub finish
35             {
36 0     0 1   my($self) = shift;
37 0           $self->active(0);
38 0     0     $self->_next_code(sub { 0 });
  0            
39 0           return $self->_finish_code->($self, @_);
40             }
41              
42             sub DESTROY
43             {
44 0     0     my($self) = shift;
45              
46 0 0         if($self->active)
    0          
47             {
48 0           $self->finish;
49             }
50             elsif(my $code = $self->_destroy_code)
51             {
52 0           $code->($self);
53             }
54             }
55              
56 0     0 1   sub total { shift->{'_count'} }
57              
58             1;
59              
60             __END__
61              
62             =head1 NAME
63              
64             Rose::DB::Object::Iterator - Iterate over a series of Rose::DB::Objects.
65              
66             =head1 SYNOPSIS
67              
68             $iterator = Rose::DB::Object::Manager->get_objects_iterator(...);
69              
70             while($object = $iterator->next)
71             {
72             # do stuff with $object...
73              
74             if(...) # bail out early
75             {
76             $iterator->finish;
77             last;
78             }
79             }
80              
81             if($iterator->error)
82             {
83             print "There was an error: ", $iterator->error;
84             }
85             else
86             {
87             print "Total: ", $iterator->total;
88             }
89              
90             =head1 DESCRIPTION
91              
92             L<Rose::DB::Object::Iterator> is an iterator object that traverses a database query, returning L<Rose::DB::Object>-derived objects for each row. L<Rose::DB::Object::Iterator> objects are created by calls to the L<get_objects_iterator|Rose::DB::Object::Manager/get_objects_iterator> method of L<Rose::DB::Object::Manager> or one of its subclasses.
93              
94             =head1 OBJECT METHODS
95              
96             =over 4
97              
98             =item B<error>
99              
100             Returns the text message associated with the last error, or false if there was no error.
101              
102             =item B<finish>
103              
104             Prematurely stop the iteration (i.e., before iterating over all of the available objects).
105              
106             =item B<next>
107              
108             Return the next L<Rose::DB::Object>-derived object. Returns false (but defined) if there are no more objects to iterate over, or undef if there was an error.
109              
110             =item B<total>
111              
112             Returns the total number of objects iterated over so far.
113              
114             =back
115              
116             =head1 AUTHOR
117              
118             John C. Siracusa (siracusa@gmail.com)
119              
120             =head1 LICENSE
121              
122             Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is
123             free software; you can redistribute it and/or modify it under the same terms
124             as Perl itself.