##
## File: DBIx/SimpleQuery/Object.pm
## Author: Steve Simms
##
## Revision: $Revision$
## Date: $Date$
##
## An object created by DBIx::SimpleQuery which holds the results of a
## query.
##

package DBIx::SimpleQuery::Object;

use strict;

use overload
    '""'   => \&as_string,
    '0+'   => \&as_integer,
    'bool' => \&as_boolean,
    '@{}'  => \&as_arrayref,
    '<<'   => \&left_shift,
    '>>'   => \&right_shift,
    '<>'   => \&as_iterative;

sub new {
    my $class = shift;
    my $params = shift;
    return bless $params, $class;
}

sub as_string {
    my $self = shift();
    my @results = @{$self->{"results"}};
    if (not scalar @results and $self->{"field_count"} == 1) {
	return "";
    }
    elsif (scalar @results == 1) {
	my $first_result = $results[0];
	if ($self->{"field_count"} == 1) {
	    my @keys = keys %{$first_result};
	    my $key = shift(@keys);
	    return $first_result->{$key};
	}
    }
    return $self->{"count"};
}

sub as_integer {
    my $self = shift();
    return $self->{"count"};
}

sub as_boolean {
    my $self = shift();
    return ($self->{"count"} ? 1 : 0);
}

sub as_arrayref {
    my $self = shift();
    return $self->{"results"};
}

sub left_shift {
    my ($self, $i) = @_;
    $i = 1 unless defined $i;
    return $self->{"results"}->[$i-1];
}

sub right_shift {
    my ($self, $i) = @_;
    $i = 1 unless defined $i;
    left_shift($self, $i*-1+1);
}

sub as_iterative {
    my $self = shift();
    return $self->{"results"}->[$self->{"iter"}++];
}

1;

__END__

=head1 NAME

DBIx::SimpleQuery::Object - An object containing the results of a DBIx::SimpleQuery::query.

=head1 SYNOPSIS

  use DBIx::SimpleQuery;
  
  DBIx::SimpleQuery::set_defaults({
      "dsn"      => "DBI:Pg:test_database",
      "user"     => "test_user",
      "password" => "test_password",
  });
  
  # Perform maintenance on users
  foreach my $user (query "SELECT * FROM users") {
      my $user_id = $user->{"user_id"};

      # Does this user have a password?
      unless (query "SELECT * FROM passwords WHERE user_id = $user_id") {
          print "User $user_id does not have a password!\n";
      }

      # How many widgets do they have?
      my $widget_count = query "SELECT * FROM widgets WHERE user_id = $user_id";
      print "User $user_id has $widget_count widgets.\n";

      # Get their first and last widgets
      my $first_widget <<= query "SELECT * FROM widgets WHERE user_id = $user_id ORDER BY time";
      my $last_widget >>= query "SELECT * FROM widgets WHERE user_id = $user_id ORDER BY time";
  }

=head1 DESCRIPTION

DBIx::SimpleQuery::Object is a background module that allows a
programmer to interact with the results of a query without having to
resort to a structure like:

  my $first_row_id = @{$results_arrayhashref}->[0]->{"user_id"};

Instead, it overloads the stringify, boolify, and other -ify functions
to return values that the programmer wants, without needing all of the
extra markup.

It should never be generated directly, but only as a result of a
DBIx::SimpleQuery::query call.  Use the synopsis above to get some
ideas of how it works.

=head1 AUTHOR

Steve Simms (ssimms@cpan.org)

=head1 COPYRIGHT

Copyright 2004 Steve Simms.  All rights reserved.

This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 SEE ALSO

DBI
DBIx::SimpleQuery

=cut