Data::ObjectDriver::ResultSet - Manage a DB query

    # Get a resultset object for Object::Widget, which inherits from
    # Data::ObjectDriver::BaseObject
    my $result = Object::Widget->result($terms, $args);

    $result->add_term({color => 'blue'});

    $result->add_limit(10);
    $result->add_offset(100);

    while (not $result->is_empty) {
        my $widget = $result->next;

        # Do stuff with $widget
    }

  $res->add_constraint({object_id => $id}, {limit => 100})

  $res->add_constraint($terms)

  $res->add_term({object_id => $id})

  $res->clear_term(qw(limit offset))

  $res->add_constraint({}, {limit => $limit})

  $res->add_limit(100)

  $res->clear_limit

  $res->add_offset(5_000)

  $res->clear_offset

  $res->add_order('ascend')

  $res->clear_order

  $idx = $res->index;

  $obj = $res->next;

  while ($bottle = $res->next){

      if ($bottle->type eq 'Bud Light'
          && $res->peek_next->type eq 'Chimay'){

          $bottle->pass; #don't spoil my palate

      }else{
          $bottle->drink;
      }
  }

  $obj = $res->prev;

  $obj = $res->curr

  my @objs = $res->slice(0, 20)

  $num = $res->count

  while (not $res->is_finished) {
      my $obj = $res->next;
      # Stuff ...
  }

  $obj = $res->first

  $obj = $res->last

  if ( $res->is_last ) {
     ## do some stuff
  }

# $Id: BaseObject.pm 418 2007-11-29 18:08:10Z garth $

package Data::ObjectDriver::ResultSet;

## Dependencies

use strict;

use base qw( Class::Accessor::Fast );
use List::Util qw(min);

## Public/_Private Accessors

__PACKAGE__->mk_accessors(qw(
                             class
                             is_finished

                             dod_debug

                             _terms
                             _args
                             _filter_terms
                             _filter_args

                             _cursor
                             _results
                             _results_loaded
                         ));

## Constructors

sub new {
    my $class = shift;
    my ($param) = @_;
    my $self = bless {}, ref $class || $class;

    $self->class($param->{class});

    $self->is_finished(0);
    $self->add_constraint($param->{terms}, $param->{args});

    $self->_cursor(-1);

    return $self;
}

sub iterator {
    my $class = shift;
    my ($objs) = @_;

    my $self = bless {}, ref $class || $class;
    $self->_results($objs);
    $self->_results_loaded(1);
    $self->_cursor(-1);
    $self->is_finished(0);

    return $self;
}

sub clone {
    my $self = shift;

    # note that this is a SHALLOW copy--any values that are references
    # will be shared between the original and the clone
    my $terms = $self->_terms ? { %{$self->_terms} } : {};
    my $args  = $self->_args  ? { %{$self->_args} }  : {};

    my $clone = $self->new({class => $self->class,
                            terms => $terms,
                            args  => $args,
                           });

    # Pull in filtered results if they've been loaded on the original object
    if ($self->_results_loaded) {
        my $res = $self->_load_results;
        $clone->_results([@$res]) if $res;
    }

    return $clone;
}

## Public Instance Methods

sub add_constraint {
    my $self = shift;
    my ($terms, $args) = @_;

    if ($terms) {
        die "First argument to 'add_constraint' must be a hash reference"
          if ref $terms ne 'HASH';

        # Get current terms and any terms we are using as a filter on existing
        # result sets
        my $cur_terms    = $self->_terms || {};
        my $filter_terms = $self->_filter_terms || {};
        foreach my $k (keys %$terms) {
            $self->_results_loaded(0) unless $cur_terms->{$k};
            $cur_terms->{$k} = $terms->{$k};
            $filter_terms->{$k} = 1 if $self->_results_loaded;
        }
        $self->_terms($cur_terms);
        $self->_filter_terms($filter_terms) if $self->_results_loaded;
    }

    if ($args) {
        die "Second argument to 'add_constraint' must be a hash reference"
          if ref $args ne 'HASH';

        my $cur_args    = $self->_args || {};
        my $filter_args = $self->_filter_args || {};
        foreach my $k (keys %$args) {
            my $val = $args->{$k};

            # If we get a limit arg that is bigger than our existing limit (and
            # we *have* an existing limit), then
            # make sure we force a requery.  Same for any filter arguments.
            # Same for offset arg that is  smaller than existing one.
            if ((($k eq 'limit')  and
            ( exists $cur_args->{'limit'} && defined $cur_args->{'limit'} && ($cur_args->{'limit'}||0)  < $val)) or
                (($k eq 'offset') and (($cur_args->{'offset'}||0) > $val)) or
                ($k eq 'filters')) {
                $self->_results_loaded(0);
            }

            $cur_args->{$k} = $val;
            $filter_args->{$k} = 1 if $self->_results_loaded;
        }
        $self->_args($cur_args);
        $self->_filter_args($filter_args) if $self->_results_loaded;
    }

    return 1;
}

sub clear_constraint {
    my $self = shift;
    my ($term_names, $arg_names) = @_;

    my $terms = $self->_terms;
    if ($term_names and $terms) {
        die "First argument to 'clear_constraint' must be an array reference"
          if ref $term_names ne 'ARRAY';

        foreach my $n (@$term_names) {
            if (delete $terms->{$n}) {
                $self->_results_loaded(0);
            }
        }
    }

    my $args = $self->_args;
    if ($arg_names and $args) {
        die "Second argument to 'clear_constraint' must be an array reference"
          if ref $arg_names ne 'ARRAY';

        foreach my $n (@$arg_names) {
            # If we get a limit arg that is bigger than our existing limit, then
            # make sure we force a requery.  Same for any filter arguments.
            # Same for offset arg that is  smaller than existing one.
            if (($n eq 'limit')  and (($args->{'limit'}||0)  > 0) or
                ($n eq 'offset') and (($args->{'offset'}||0) > 0) or
                ($n eq 'filters')) {
                $self->_results_loaded(0);
            }
            delete $args->{$n};
        }
    }

    return 1;
}

sub add_term        { shift->add_constraint($_[0])                    }
sub clear_term      { shift->clear_constraint(\@_)                    }
sub get_term        { my $self = shift;
                      $self->_terms && $self->_terms->{$_[0]}         }

sub add_limit       { shift->add_constraint(undef, {limit => $_[0]})  }
sub clear_limit     { shift->clear_constraint(undef, ['limit'])       }
sub get_limit       { my $self = shift;
                      $self->_args && $self->_args->{limit}           }

sub add_offset      { shift->add_constraint(undef, {offset => $_[0]}) }
sub clear_offset    { shift->clear_constraint(undef, ['offset'])      }
sub get_offset      { my $self = shift;
                      $self->_args && $self->_args->{offset}          }

sub add_order       { shift->add_constraint(undef, {sort => $_[0]})   }
sub clear_order     { shift->clear_constraint(undef, ['sort'])        }
sub get_order       { my $self = shift;
                      $self->_args && $self->_args->{sort}           }

sub add_filters     { shift->add_constraint(undef, {filters => $_[0]}) }
sub clear_filters   { shift->clear_constraint(undef, ['filters'])      }
sub get_filters     { my $self = shift;
                      $self->_args && $self->_args->{filters}          }
sub index {
    my $self = shift;

    return $self->_cursor;
}

sub next {
    my $self = shift;

    return if $self->is_finished;

    $self->_cursor($self->_cursor + 1);

    # Load the results and return an object
    my $results = $self->_load_results;

    my $obj = $results->[$self->_cursor];

    if ($obj) {
        return $obj;
    } else {
        $self->is_finished(1);
        return;
    }
}

# look at next() without incrementing the cursor
# like if you just want to see what's coming down the road at you
sub peek_next {
    my $self = shift;

    return if $self->is_finished;

    # Load the results and return an object
    my $results = $self->_load_results;

    my $obj = $results->[$self->_cursor + 1];

    return $obj;
}



sub prev {
    my $self = shift;

    $self->_cursor($self->_cursor - 1);

    # Boundary check
    return if $self->_cursor == -1;

    # Load the results and return an object
    my $results = $self->_load_results;

    my $obj = $results->[$self->_cursor];
    if ($obj) {
        return $obj;
    } else {
        return;
    }
}

sub curr {
    my $self = shift;

    return $self->_load_results->[$self->_cursor];
}

sub slice {
    my $self = shift;
    my ($start, $end) = @_;

    # Do we already have results?
    if ($self->_results) {
        return [ @{ $self->_results }[$start..min($self->count-1, $end)] ];
    }

    my $limit = $end - $start + 1;

    $self->add_offset($start);
    $self->add_limit($limit);

    my $r = $self->_load_results;

    return $r;
}

sub all {
    my $self = shift;

    return unless $self->count;

    my @obj;
    push @obj, $self->first;
    while (my $obj = $self->next) {
        push @obj, $obj;
    }

    $self->rewind;
    return @obj;
}

sub count {
    my $self = shift;

    # Get/load the results if we already have them
    if ($self->_results_loaded or $self->get_limit) {
        my $results = $self->_load_results;
        return scalar @$results;
    } else {
        local $Data::ObjectDriver::DEBUG = 1 if $self->dod_debug;
        return $self->class->count($self->_terms, $self->_args);
    }
}

sub first {
    my $self = shift;

    # Clear is finished in case they are comming back from the last element
    $self->is_finished(0);
    $self->_cursor(0);

    my $results = $self->_load_results;

    my $obj = $results->[$self->_cursor];
    if ($obj) {
        return $obj;
    } else {
        return;
    }
}

sub last {
    my $self = shift;
    my $results;

    $results = $self->_load_results;
    $self->_cursor($#$results);

    return $results->[$self->_cursor];
}

sub is_last {
    my $self = shift;
    my $results = $self->_load_results;
    return (scalar @{$results} == $self->_cursor + 1) ? 1 : 0;
}

## Private Instance Methods

sub _filtered_results {
    my $self = shift;
    my $results      = $self->_results;
    my $filter_terms = $self->_filter_terms;
    my $filter_args  = $self->_filter_args;

    # Return right away if we don't have any new filters
    return $results unless $filter_terms or $filter_args;

    my $new_results;

    # Check terms
    if ($filter_terms) {
        while (my $obj = shift @$results) {
            push @$new_results, $obj if $self->_in_terms_filter($obj);
        }
    } else {
        $new_results = $results;
    }

    # Check args
    if ($filter_args) {
        if ($filter_args->{sort}) {
            @$new_results = sort { $self->_dod_sort($a, $b) } @$new_results;
        }

        # See if we've got a new limit and offset
        if ($filter_args->{offset}) {
            my $offset = $self->_args->{offset};
            splice @$new_results, 0, $offset;
        }

        if ($filter_args->{limit}) {
            my $limit = $self->_args->{limit};
            if (scalar @$new_results > $limit) {
                # Truncate the array
                splice @$new_results, $limit, $#$new_results;
            }
        }
    }

    $self->_filter_terms(undef);
    $self->_filter_args(undef);

    $self->_results($new_results);

    return $new_results;
}

sub _dod_sort {
    my $self = shift;
    my ($a, $b) = @_;
    my $sort = $self->_args->{sort};

    foreach my $order_data (@$sort) {
        my $col = $order_data->{column};
        my $dir = $order_data->{direction};
        my $result;

        $result = ($dir eq 'ascend') ? $a->$col cmp $b->$col
                                     : $b->$col cmp $a->$col;

        # Return the sort result unless they are the same
        return $result unless $result == 0;
    }

    return 0;
}

sub _in_terms_filter {
    my $self = shift;
    my ($obj) = @_;

    # Always matches filter if we don't have any filters
    return 1 unless $self->_filter_terms;

    if ($self->_filter_terms) {
        # Look through each filter
        foreach my $key (keys %{$self->_filter_terms}) {
            # If something doesn't match return with undef
            if ($obj->$key ne $self->_terms->{$key}) {
                return;
            }
        }
    }

    return 1;
}

sub _load_results {
    my $self = shift;

    # If results are already loaded, see if they need to be filtered and return
    # them
    if ($self->_results_loaded) {
        my $results = $self->_filtered_results;

        return $self->_results;
    }

    # An iterator only ResultSet doesn't have a class (or any paramaters for
    # that matter) so don't try to search for anything.
    return unless $self->class;

    local $Data::ObjectDriver::DEBUG = 1 if $self->dod_debug;
    my @r = $self->class->search($self->_terms, $self->_args);

    $self->_results(\@r);
    $self->_results_loaded(1);

    return \@r;
}

sub rewind {
    my $self = shift;
    $self->is_finished(0);
    $self->_cursor(-1);
    return $self;
}
1;

__END__