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 $rs=MyApp::DB::Class->search(registered=>1);
  17
  18 =head1 DESCRIPTION
  19
  20 The resultset is also known as an iterator.
  21
  22 =head1 METHODS
  23
  24 =over 4
  25
  26 =item new  <db_class> <attrs>
  27
  28 The resultset 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 ($class, $db_class, $attrs) = @_;
  35   #use Data::Dumper; warn Dumper(@_);
  36   $class = ref $class if ref $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     source => $db_class,
  61     cols => $attrs->{cols},
  62     cond => $attrs->{where},
  63     from => $attrs->{from},
  64     count => undef,
  65     pager => undef,
  66     attrs => $attrs };
  67   bless ($new, $class);
  68   $new->pager if ($attrs->{page});
  69   return $new;
  70 }
  71
  72 =item search
  73
  74   my @obj    = $rs->search({ foo => 3 }); # "... WHERE foo = 3"
  75   my $new_rs = $rs->search({ foo => 3 });
  76
  77 If you need to pass in additional attributes but no additional condition,
  78 call it as ->search(undef, \%attrs);
  79
  80   my @all = $class->search({}, { cols => [qw/foo bar/] }); # "SELECT foo, bar FROM $class_table"
  81
  82 =cut
  83
  84 sub search {
  85   my $self = shift;
  86
  87   #use Data::Dumper;warn Dumper(@_);
  88
  89   my $attrs = { %{$self->{attrs}} };
  90   if (@_ > 1 && ref $_[$#_] eq 'HASH') {
  91     $attrs = { %{ pop(@_) } };
  92   }
  93
  94   my $where = ((@_ == 1 || ref $_[0] eq "HASH") ? shift : {@_});
  95   if (defined $where) {
  96     $where = (defined $attrs->{where}
  97                 ? { '-and' => [ $where, $attrs->{where} ] }
  98                 : $where);
  99     $attrs->{where} = $where;
 100   }
 101
 102   my $rs = $self->new($self->{source}, $attrs);
 103
 104   return (wantarray ? $rs->all : $rs);
 105 }
 106
 107 =item search_literal
 108   my @obj    = $rs->search_literal($literal_where_cond, @bind);
 109   my $new_rs = $rs->search_literal($literal_where_cond, @bind);
 110
 111 Pass a literal chunk of SQL to be added to the conditional part of the
 112 resultset
 113
 114 =cut
 115 sub search_literal {
 116   my ($self, $cond, @vals) = @_;
 117   my $attrs = (ref $vals[$#vals] eq 'HASH' ? { %{ pop(@vals) } } : {});
 118   $attrs->{bind} = [ @{$self->{attrs}{bind}||[]}, @vals ];
 119   return $self->search(\$cond, $attrs);
 120 }
 121
 122 =item cursor
 123
 124 Return a storage driven cursor to the given resultset.
 125
 126 =cut
 127
 128 sub cursor {
 129   my ($self) = @_;
 130   my ($source, $attrs) = @{$self}{qw/source attrs/};
 131   if ($attrs->{page}) {
 132     $attrs->{rows} = $self->pager->entries_per_page;
 133     $attrs->{offset} = $self->pager->skipped;
 134   }
 135   return $self->{cursor}
 136     ||= $source->storage->select($self->{from}, $self->{cols},
 137           $attrs->{where},$attrs);
 138 }
 139
 140 =item search_like
 141
 142 Identical to search except defaults to 'LIKE' instead of '=' in condition
 143
 144 =cut
 145
 146 sub search_like {
 147   my $class    = shift;
 148   my $attrs = { };
 149   if (@_ > 1 && ref $_[$#_] eq 'HASH') {
 150     $attrs = pop(@_);
 151   }
 152   my $query    = ref $_[0] eq "HASH" ? { %{shift()} }: {@_};
 153   $query->{$_} = { 'like' => $query->{$_} } for keys %$query;
 154   return $class->search($query, { %$attrs });
 155 }
 156
 157 =item slice <first> <last>
 158
 159 return a number of elements from the given resultset.
 160
 161 =cut
 162
 163 sub slice {
 164   my ($self, $min, $max) = @_;
 165   my $attrs = { %{ $self->{attrs} || {} } };
 166   $self->{source}->throw("Can't slice without where") unless $attrs->{where};
 167   $attrs->{offset} = $min;
 168   $attrs->{rows} = ($max ? ($max - $min + 1) : 1);
 169   my $slice = $self->new($self->{source}, $attrs);
 170   return (wantarray ? $slice->all : $slice);
 171 }
 172
 173 =item next
 174
 175 Returns the next element in this resultset.
 176
 177 =cut
 178
 179 sub next {
 180   my ($self) = @_;
 181   my @row = $self->cursor->next;
 182   return unless (@row);
 183   return $self->_construct_object(@row);
 184 }
 185
 186 sub _construct_object {
 187   my ($self, @row) = @_;
 188   my @cols = @{ $self->{attrs}{cols} };
 189   s/^me\.// for @cols;
 190   @cols = grep { /\(/ or ! /\./ } @cols;
 191   my $new;
 192   unless ($self->{attrs}{prefetch}) {
 193     $new = $self->{source}->_row_to_object(\@cols, \@row);
 194   } else {
 195     my @main = splice(@row, 0, scalar @cols);
 196     $new = $self->{source}->_row_to_object(\@cols, \@main);
 197     PRE: foreach my $pre (@{$self->{attrs}{prefetch}}) {
 198       my $rel_obj = $self->{source}->_relationships->{$pre};
 199       my $pre_class = $self->{source}->resolve_class($rel_obj->{class});
 200       my @pre_cols = $pre_class->_select_columns;
 201       my @vals = splice(@row, 0, scalar @pre_cols);
 202       my $fetched = $pre_class->_row_to_object(\@pre_cols, \@vals);
 203       $self->{source}->throw("No accessor for prefetched $pre")
 204         unless defined $rel_obj->{attrs}{accessor};
 205       if ($rel_obj->{attrs}{accessor} eq 'single') {
 206         foreach my $pri ($rel_obj->{class}->primary_columns) {
 207           unless (defined $fetched->get_column($pri)) {
 208             undef $fetched;
 209             last;
 210           }
 211         }
 212         $new->{_relationship_data}{$pre} = $fetched;
 213       } elsif ($rel_obj->{attrs}{accessor} eq 'filter') {
 214         $new->{_inflated_column}{$pre} = $fetched;
 215       } else {
 216         $self->{source}->throw("Don't know how to store prefetched $pre");
 217       }
 218     }
 219   }
 220   $new = $self->{attrs}{record_filter}->($new)
 221     if exists $self->{attrs}{record_filter};
 222   return $new;
 223 }
 224
 225 =item count
 226
 227 Performs an SQL count with the same query as the resultset was built
 228 with to find the number of elements. If passed arguments, does a search
 229 on the resultset and counts the results of that.
 230
 231 =cut
 232
 233 sub count {
 234   my $self = shift;
 235   return $self->search(@_)->count if @_ && defined $_[0];
 236   my $attrs = { %{ $self->{attrs} } };
 237   unless ($self->{count}) {
 238     # offset and order by are not needed to count
 239     delete $attrs->{$_} for qw/offset order_by/;
 240
 241     my @cols = 'COUNT(*)';
 242     $self->{count} = $self->{source}->storage->select_single(
 243         $self->{from}, \@cols, $self->{cond}, $attrs);
 244   }
 245   return 0 unless $self->{count};
 246   return $self->{pager}->entries_on_this_page if ($self->{pager});
 247   return ( $attrs->{rows} && $attrs->{rows} < $self->{count} )
 248     ? $attrs->{rows}
 249     : $self->{count};
 250 }
 251
 252 =item count_literal
 253
 254 Calls search_literal with the passed arguments, then count
 255
 256 =cut
 257
 258 sub count_literal { shift->search_literal(@_)->count; }
 259
 260 =item all
 261
 262 Returns all elements in the resultset. Is called implictly if the search
 263 method is used in list context.
 264
 265 =cut
 266
 267 sub all {
 268   my ($self) = @_;
 269   return map { $self->_construct_object(@$_); }
 270            $self->cursor->all;
 271 }
 272
 273 =item reset
 274
 275 Reset this resultset's cursor, so you can iterate through the elements again.
 276
 277 =cut
 278
 279 sub reset {
 280   my ($self) = @_;
 281   $self->cursor->reset;
 282   return $self;
 283 }
 284
 285 =item first
 286
 287 resets the resultset and returns the first element.
 288
 289 =cut
 290
 291 sub first {
 292   return $_[0]->reset->next;
 293 }
 294
 295 =item delete
 296
 297 Deletes all elements in the resultset.
 298
 299 =cut
 300
 301 sub delete {
 302   my ($self) = @_;
 303   $_->delete for $self->all;
 304   return 1;
 305 }
 306
 307 *delete_all = \&delete; # Yeah, yeah, yeah ...
 308
 309 =item pager
 310
 311 Returns a L<Data::Page> object for the current resultset. Only makes
 312 sense for queries with page turned on.
 313
 314 =cut
 315
 316 sub pager {
 317   my ($self) = @_;
 318   my $attrs = $self->{attrs};
 319   delete $attrs->{offset};
 320   my $rows_per_page = delete $attrs->{rows} || 10;
 321   $self->{pager} ||= Data::Page->new(
 322     $self->count, $rows_per_page, $attrs->{page} || 1);
 323   $attrs->{rows} = $rows_per_page;
 324   return $self->{pager};
 325 }
 326
 327 =item page <page>
 328
 329 Returns a new resultset representing a given page.
 330
 331 =cut
 332
 333 sub page {
 334   my ($self, $page) = @_;
 335   my $attrs = $self->{attrs};
 336   $attrs->{page} = $page;
 337   return $self->new($self->{source}, $attrs);
 338 }
 339
 340 =back
 341
 342 =head1 Attributes
 343
 344 The resultset is responsible for handling the various attributes that
 345 can be passed in with the search functions. Here's an overview of them:
 346
 347 =over 4
 348
 349 =item order_by
 350
 351 Which column to order the results by.
 352
 353 =item cols
 354
 355 Which cols should be retrieved on the first search.
 356
 357 =item join
 358
 359 Contains a list of relations that should be joined for this query. Can also
 360 contain a hash referece to refer to that relation's relations.
 361
 362 =item from
 363
 364 This attribute can contain a arrayref of  elements. each element can be another
 365 arrayref, to nest joins, or it can be a hash which represents the two sides
 366 of the join.
 367
 368 *NOTE* Use this on your own risk. This allows you to shoot your foot off!
 369
 370 =item page
 371
 372 Should the resultset be paged? This can also be enabled by using the
 373 'page' option.
 374
 375 =item rows
 376
 377 For paged resultsset, how  many rows per page
 378
 379 =item  offset
 380
 381 For paged resultsset, which page to start on.
 382
 383 =back
 384
 385 1;