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