lib/DBIx/Class/ResultSet.pm

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