/ 
Fey-ORM-0.10
River stage one • 2 direct dependents • 3 total dependents
/ Fey::Object::Iterator

NAME

Fey::Object::Iterator - Wraps a DBI statement handle to construct objects from the results

SYNOPSIS

use Fey::Object::Iterator;

my $iter =
    Fey::Object::Iterator->new
        ( classes     => 'MyApp::User',
          handle      => $sth,
          bind_params => \@bind,
        );

print $iter->index(); # 0

while ( my $user = $iter->next() )
{
    print $iter->index(); # 1, 2, 3, ...
    print $user->username();
}

$iter->reset();

DESCRIPTION

This class implements an iterator on top of a DBI statement handle. Each call to next() returns one or more objects based on the data returned by the statement handle.

METHODS

This class provides the following methods:

Fey::Object::Iterator->new(...)

This method constructs a new iterator. It accepts the following parameters:

  • classes

    This can be a single class name, or an array reference of class names. These should be classes associated with the tables from which data is being SELECTed. The iterator will return an object of each class in order when $iterator->next() is called.

  • handle

    This should be a prepared, but not yet executed, DBI statement handle. Obviously, the statement handle should be for a SELECT statement.

  • bind_params

    This should be an array reference of one or more bind params to be passed to $sth->execute().

$iterator->index()

This returns the current index value of the iterator. When the object is first constructed, this index is 0, and it is incremented once for each row fetched by calling $iteartor->next().

$iterator->next()

This returns the next set of objects, based on data retrieved by the query. In list context this returns all the objects. In scalar context it returns the first object.

It is possible that one or more of the objects it returns will be undefined, though this should really only happen with an outer join. The statement handle will be executed the first time this method is called.

If the statement handle is exhausted, this method returns false.

$iterator->all()

This returns all of the remaining sets of objects. If the iterator is for a single class, it returns a list of objects of that class. If it is for multiple objects, it returns a list of array references.

$iterator->next_as_hash()

Returns the next set of objects as a hash. The keys are the names of the object's associated table.

If the statement handle is exhausted, this method returns false.

$iterator->all_as_hashes()

This returns all of the remaining sets of objects as a list of hash references. Each hash ref is keyed on the table name of the associated object's class.

$iterator->reset()

Resets the iterator so that the next call to $iterator->next() returns the first objects. Internally this means that the statement handle will be executed again. It's possible that data will have changed in the DBMS since then, meaning that the iterator will return different objects after a reset.

$iterator->DEMOLISH()

This method will call $sth->finish() on its DBI statment handle if necessary.

AUTHOR

Dave Rolsky, <autarch@urth.org>

BUGS

See Fey::ORM for details.

COPYRIGHT & LICENSE

Copyright 2006-2008 Dave Rolsky, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module.