pod fixes
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Storage / DBI / Cursor.pm
CommitLineData
5cf243f6 1package DBIx::Class::Storage::DBI::Cursor;
28927b50 2
3use base qw/DBIx::Class::Cursor/;
4
5use strict;
6use warnings;
7
5cf243f6 8=head1 NAME
9
10DBIx::Class::Storage::DBI::Cursor - Object representing a query cursor on a
11resultset.
12
13=head1 SYNOPSIS
14
15 my $cursor = $schema->resultset('CD')->cursor();
16 my $first_cd = $cursor->next;
17
18=head1 DESCRIPTION
19
20A Cursor represents a query cursor on a L<DBIx::Class::ResultSet> object. It
21allows for traversing the result set with L</next>, retrieving all results with
22L</all> and resetting the cursor with L</reset>.
23
24Usually, you would use the cursor methods built into L<DBIx::Class::ResultSet>
25to traverse it. See L<DBIx::Class::ResultSet/next>,
26L<DBIx::Class::ResultSet/reset> and L<DBIx::Class::ResultSet/all> for more
27information.
28
29=head1 METHODS
30
31=head2 new
32
5cf243f6 33Returns a new L<DBIx::Class::Storage::DBI::Cursor> object.
34
35=cut
36
28927b50 37sub new {
cb5f2eea 38 my ($class, $storage, $args, $attrs) = @_;
28927b50 39 #use Data::Dumper; warn Dumper(@_);
cb5f2eea 40 $class = ref $class if ref $class;
28927b50 41 my $new = {
cb5f2eea 42 storage => $storage,
28927b50 43 args => $args,
44 pos => 0,
1346e22d 45 attrs => $attrs,
dbaee748 46 _dbh_gen => $storage->{_dbh_gen},
1346e22d 47 };
48
cb5f2eea 49 return bless ($new, $class);
28927b50 50}
51
5cf243f6 52=head2 next
53
21b5c39d 54=over 4
55
ebc77b53 56=item Arguments: none
21b5c39d 57
d601dc88 58=item Return Value: \@row_columns
21b5c39d 59
5cf243f6 60=back
61
685dad64 62Advances the cursor to the next row and returns an array of column
63values (the result of L<DBI/fetchrow_array> method).
5cf243f6 64
65=cut
66
dbaee748 67sub _dbh_next {
68 my ($storage, $dbh, $self) = @_;
1346e22d 69
dbaee748 70 $self->_check_dbh_gen;
cb5f2eea 71 if ($self->{attrs}{rows} && $self->{pos} >= $self->{attrs}{rows}) {
71e65b39 72 $self->{sth}->finish if $self->{sth}->{Active};
cb5f2eea 73 delete $self->{sth};
74 $self->{done} = 1;
75 }
76 return if $self->{done};
77 unless ($self->{sth}) {
dbaee748 78 $self->{sth} = ($storage->_select(@{$self->{args}}))[1];
5c91499f 79 if ($self->{attrs}{software_limit}) {
80 if (my $offset = $self->{attrs}{offset}) {
cb5f2eea 81 $self->{sth}->fetch for 1 .. $offset;
5c91499f 82 }
83 }
28927b50 84 }
cb5f2eea 85 my @row = $self->{sth}->fetchrow_array;
86 if (@row) {
87 $self->{pos}++;
88 } else {
89 delete $self->{sth};
90 $self->{done} = 1;
91 }
28927b50 92 return @row;
93}
94
dbaee748 95sub next {
96 my ($self) = @_;
97 $self->{storage}->dbh_do($self->can('_dbh_next'), $self);
98}
99
5cf243f6 100=head2 all
101
21b5c39d 102=over 4
103
ebc77b53 104=item Arguments: none
21b5c39d 105
d601dc88 106=item Return Value: \@row_columns+
21b5c39d 107
5cf243f6 108=back
109
21b5c39d 110Returns a list of arrayrefs of column values for all rows in the
111L<DBIx::Class::ResultSet>.
5cf243f6 112
113=cut
114
dbaee748 115sub _dbh_all {
116 my ($storage, $dbh, $self) = @_;
1346e22d 117
dbaee748 118 $self->_check_dbh_gen;
cb5f2eea 119 $self->{sth}->finish if $self->{sth}->{Active};
120 delete $self->{sth};
dbaee748 121 my ($rv, $sth) = $storage->_select(@{$self->{args}});
1a14aa3f 122 return @{$sth->fetchall_arrayref};
123}
124
dbaee748 125sub all {
126 my ($self) = @_;
6296f45b 127 if ($self->{attrs}{software_limit}
128 && ($self->{attrs}{offset} || $self->{attrs}{rows})) {
129 return $self->SUPER::all;
130 }
dbaee748 131 $self->{storage}->dbh_do($self->can('_dbh_all'), $self);
132}
133
5cf243f6 134=head2 reset
135
5cf243f6 136Resets the cursor to the beginning of the L<DBIx::Class::ResultSet>.
137
138=cut
139
28927b50 140sub reset {
141 my ($self) = @_;
1346e22d 142
dbaee748 143 # No need to care about failures here
144 eval { $self->{sth}->finish if $self->{sth} && $self->{sth}->{Active} };
1346e22d 145 $self->_soft_reset;
146}
147
148sub _soft_reset {
149 my ($self) = @_;
150
cb5f2eea 151 delete $self->{sth};
cb5f2eea 152 delete $self->{done};
dbaee748 153 $self->{pos} = 0;
28927b50 154 return $self;
155}
156
dbaee748 157sub _check_dbh_gen {
1346e22d 158 my ($self) = @_;
159
dbaee748 160 if($self->{_dbh_gen} != $self->{storage}->{_dbh_gen}) {
161 $self->{_dbh_gen} = $self->{storage}->{_dbh_gen};
162 $self->_soft_reset;
1346e22d 163 }
164}
165
28927b50 166sub DESTROY {
167 my ($self) = @_;
1346e22d 168
dbaee748 169 # None of the reasons this would die matter if we're in DESTROY anyways
19fb8520 170 local $@;
dbaee748 171 eval { $self->{sth}->finish if $self->{sth} && $self->{sth}->{Active} };
28927b50 172}
173
1741;