Merge 'trunk' into 'DBIx-Class-C3'
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / ResultSet.pm
CommitLineData
89c0a5a2 1package DBIx::Class::ResultSet;
2
3use strict;
4use warnings;
5use overload
6 '0+' => 'count',
7 fallback => 1;
3c5b25c5 8use Data::Page;
89c0a5a2 9
ee38fa40 10=head1 NAME
11
38659261 12DBIX::Class::ResultSet - Responsible for fetching and creating resultset.
ee38fa40 13
14=head1 SYNOPSIS;
15
16$rs=MyApp::DB::Class->search(registered=>1);
17
18=head1 DESCRIPTION
19
38659261 20The resultset is also known as an iterator.
ee38fa40 21
22=head1 METHODS
23
24=over 4
25
26=item new <db_class> <attrs>
27
38659261 28The resultset constructor. Takes a db class and an
ee38fa40 29attribute hash (see below for more info on attributes)
30
31=cut
32
89c0a5a2 33sub new {
7624b19f 34 my ($it_class, $db_class, $attrs) = @_;
89c0a5a2 35 #use Data::Dumper; warn Dumper(@_);
36 $it_class = ref $it_class if ref $it_class;
37 $attrs = { %{ $attrs || {} } };
c7ce65e6 38 my %seen;
39 $attrs->{cols} ||= [ map { "me.$_" } $db_class->_select_columns ];
40 $attrs->{from} ||= [ { 'me' => $db_class->_table_name } ];
fef5d100 41 if ($attrs->{join}) {
c7ce65e6 42 foreach my $j (ref $attrs->{join} eq 'ARRAY'
43 ? (@{$attrs->{join}}) : ($attrs->{join})) {
44 if (ref $j eq 'HASH') {
45 $seen{$_} = 1 foreach keys %$j;
46 } else {
47 $seen{$j} = 1;
48 }
49 }
50 push(@{$attrs->{from}}, $db_class->_resolve_join($attrs->{join}, 'me'));
51 }
52 foreach my $pre (@{$attrs->{prefetch} || []}) {
53 push(@{$attrs->{from}}, $db_class->_resolve_join($pre, 'me'))
54 unless $seen{$pre};
55 push(@{$attrs->{cols}},
56 map { "$pre.$_" }
ddab752c 57 $db_class->_relationships->{$pre}->{class}->_select_columns);
fef5d100 58 }
89c0a5a2 59 my $new = {
60 class => $db_class,
fef5d100 61 cols => $attrs->{cols} || [ $db_class->_select_columns ],
89c0a5a2 62 cond => $attrs->{where},
fef5d100 63 from => $attrs->{from} || $db_class->_table_name,
3c5b25c5 64 count => undef,
65 pager => undef,
89c0a5a2 66 attrs => $attrs };
9229f20a 67 bless ($new, $it_class);
68 $new->pager if ($attrs->{page});
69 return $new;
89c0a5a2 70}
71
ee38fa40 72=item cursor
73
38659261 74Return a storage driven cursor to the given resultset.
ee38fa40 75
76=cut
77
73f58123 78sub cursor {
79 my ($self) = @_;
80 my ($db_class, $attrs) = @{$self}{qw/class attrs/};
3c5b25c5 81 if ($attrs->{page}) {
82 $attrs->{rows} = $self->pager->entries_per_page;
83 $attrs->{offset} = $self->pager->skipped;
84 }
73f58123 85 return $self->{cursor}
fef5d100 86 ||= $db_class->storage->select($self->{from}, $self->{cols},
73f58123 87 $attrs->{where},$attrs);
88}
89
ee38fa40 90=item slice <first> <last>
91
38659261 92return a number of elements from the given resultset.
ee38fa40 93
94=cut
95
89c0a5a2 96sub slice {
97 my ($self, $min, $max) = @_;
98 my $attrs = { %{ $self->{attrs} || {} } };
99 $self->{class}->throw("Can't slice without where") unless $attrs->{where};
100 $attrs->{offset} = $min;
101 $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
7624b19f 102 my $slice = $self->new($self->{class}, $attrs);
89c0a5a2 103 return (wantarray ? $slice->all : $slice);
104}
105
ee38fa40 106=item next
107
38659261 108Returns the next element in this resultset.
ee38fa40 109
110=cut
111
89c0a5a2 112sub next {
113 my ($self) = @_;
73f58123 114 my @row = $self->cursor->next;
89c0a5a2 115 return unless (@row);
c7ce65e6 116 return $self->_construct_object(@row);
117}
118
119sub _construct_object {
120 my ($self, @row) = @_;
90f3f5ff 121 my @cols = @{ $self->{attrs}{cols} };
122 s/^me\.// for @cols;
3cbddeb1 123 @cols = grep { /\(/ or ! /\./ } @cols;
33ce49d6 124 my $new;
c7ce65e6 125 unless ($self->{attrs}{prefetch}) {
33ce49d6 126 $new = $self->{class}->_row_to_object(\@cols, \@row);
c7ce65e6 127 } else {
128 my @main = splice(@row, 0, scalar @cols);
33ce49d6 129 $new = $self->{class}->_row_to_object(\@cols, \@main);
c7ce65e6 130 PRE: foreach my $pre (@{$self->{attrs}{prefetch}}) {
131 my $rel_obj = $self->{class}->_relationships->{$pre};
dd417d06 132 my $pre_class = $self->{class}->resolve_class($rel_obj->{class});
133 my @pre_cols = $pre_class->_select_columns;
c7ce65e6 134 my @vals = splice(@row, 0, scalar @pre_cols);
dd417d06 135 my $fetched = $pre_class->_row_to_object(\@pre_cols, \@vals);
c7ce65e6 136 $self->{class}->throw("No accessor for prefetched $pre")
137 unless defined $rel_obj->{attrs}{accessor};
138 if ($rel_obj->{attrs}{accessor} eq 'single') {
139 foreach my $pri ($rel_obj->{class}->primary_columns) {
7cd300ea 140 unless (defined $fetched->get_column($pri)) {
141 undef $fetched;
142 last;
143 }
c7ce65e6 144 }
145 $new->{_relationship_data}{$pre} = $fetched;
146 } elsif ($rel_obj->{attrs}{accessor} eq 'filter') {
147 $new->{_inflated_column}{$pre} = $fetched;
148 } else {
3125eb1f 149 $self->{class}->throw("Don't know how to store prefetched $pre");
c7ce65e6 150 }
151 }
c7ce65e6 152 }
33ce49d6 153 $new = $self->{attrs}{record_filter}->($new)
154 if exists $self->{attrs}{record_filter};
155 return $new;
89c0a5a2 156}
157
ee38fa40 158=item count
159
160Performs an SQL count with the same query as the resultset was built
161with to find the number of elements.
162
163=cut
164
165
89c0a5a2 166sub count {
167 my ($self) = @_;
7624b19f 168 my $db_class = $self->{class};
59f8e584 169 my $attrs = { %{ $self->{attrs} } };
3c5b25c5 170 unless ($self->{count}) {
171 # offset and order by are not needed to count
172 delete $attrs->{$_} for qw/offset order_by/;
173
174 my @cols = 'COUNT(*)';
fef5d100 175 $self->{count} = $db_class->storage->select_single($self->{from}, \@cols,
3c5b25c5 176 $self->{cond}, $attrs);
177 }
178 return 0 unless $self->{count};
9229f20a 179 return $self->{pager}->entries_on_this_page if ($self->{pager});
3c5b25c5 180 return ( $attrs->{rows} && $attrs->{rows} < $self->{count} )
59f8e584 181 ? $attrs->{rows}
3c5b25c5 182 : $self->{count};
89c0a5a2 183}
184
ee38fa40 185=item all
186
38659261 187Returns all elements in the resultset. Is called implictly if the search
ee38fa40 188method is used in list context.
189
190=cut
191
89c0a5a2 192sub all {
193 my ($self) = @_;
c7ce65e6 194 return map { $self->_construct_object(@$_); }
73f58123 195 $self->cursor->all;
89c0a5a2 196}
197
ee38fa40 198=item reset
199
38659261 200Reset this resultset's cursor, so you can iterate through the elements again.
ee38fa40 201
202=cut
203
89c0a5a2 204sub reset {
205 my ($self) = @_;
73f58123 206 $self->cursor->reset;
89c0a5a2 207 return $self;
208}
209
ee38fa40 210=item first
211
38659261 212resets the resultset and returns the first element.
ee38fa40 213
214=cut
215
89c0a5a2 216sub first {
217 return $_[0]->reset->next;
218}
219
ee38fa40 220=item delete
221
38659261 222Deletes all elements in the resultset.
ee38fa40 223
224=cut
225
28927b50 226sub delete {
89c0a5a2 227 my ($self) = @_;
228 $_->delete for $self->all;
229 return 1;
230}
231
28927b50 232*delete_all = \&delete; # Yeah, yeah, yeah ...
233
ee38fa40 234=item pager
235
236Returns a L<Data::Page> object for the current resultset. Only makes
237sense for queries with page turned on.
238
239=cut
240
3c5b25c5 241sub pager {
242 my ($self) = @_;
243 my $attrs = $self->{attrs};
244 delete $attrs->{offset};
245 my $rows_per_page = delete $attrs->{rows} || 10;
246 $self->{pager} ||= Data::Page->new(
247 $self->count, $rows_per_page, $attrs->{page} || 1);
248 $attrs->{rows} = $rows_per_page;
249 return $self->{pager};
250}
251
ee38fa40 252=item page <page>
253
38659261 254Returns a new resultset representing a given page.
ee38fa40 255
256=cut
257
3c5b25c5 258sub page {
259 my ($self, $page) = @_;
260 my $attrs = $self->{attrs};
261 $attrs->{page} = $page;
262 return $self->new($self->{class}, $attrs);
263}
264
ee38fa40 265=back
076652e8 266
267=head1 Attributes
268
38659261 269The resultset is responsible for handling the various attributes that
076652e8 270can be passed in with the search functions. Here's an overview of them:
271
272=over 4
273
274=item order_by
275
276Which column to order the results by.
ee38fa40 277
278=item cols
279
280Which cols should be retrieved on the first search.
281
282=item join
283
284Contains a list of relations that should be joined for this query. Can also
285contain a hash referece to refer to that relation's relations.
286
287=item from
288
289This attribute can contain a arrayref of elements. each element can be another
290arrayref, to nest joins, or it can be a hash which represents the two sides
291of the join.
292
293*NOTE* Use this on your own risk. This allows you to shoot your foot off!
294
076652e8 295=item page
296
297Should the resultset be paged? This can also be enabled by using the
298'page' option.
299
300=item rows
301
302For paged resultsset, how many rows per page
303
304=item offset
305
306For paged resultsset, which page to start on.
307
308=back
309
89c0a5a2 3101;