NAME
    DBIx::Iterator - Query your database using iterators and save memory

VERSION
    version 0.0.1

SYNOPSIS
        # Create an iterator for a simple DBI query
        my $db = DBIx::Iterator->new( DBI->connect('...') );
        my $it = $db->query("SELECT id, name FROM person");
        while ( my $row = $it->() ) {
            say $row->{'id'} . ": " . $row->{'name'};
            # Do something with $row...
        }

        # We have a basic class here that knows nothing about iterators
        package Person;
        use Moose;

        has 'id'   => ( is => 'ro', isa => 'Int' );
        has 'name' => ( is => 'ro', isa => 'Str' );

        sub label {
            my ($self) = @_;
            return $self->id . ": " . $self->name;
        }

        # Then we have a role that knows how to create instances
        # from iterators
        package FromIterator;
        use Moose::Role;

        sub new_from_iterator {
            my ($self, $it) = @_;
            return sub {
                my $row = $it->();
                return unless defined $row;
                return $self->new($row);
            }
        }

        # Then we apply the role to the Person class and use
        # our plain database iterator that produces hashes to
        # now create Person instances instead.

        package main;
        use Moose::util qw(apply_all_roles);
        my $p = apply_all_roles('Person', 'FromIterator');
        my $it = $p->new_from_iterator(
            $db->query("SELECT * FROM person")
        );
        while ( my $person = $it->() ) {
            say $person->label;
            # Do something with $person...
        }

DESCRIPTION
    Iterators are a nice way to perform operations on large datasets without
    having to keep all of the data you're working on in memory at the same
    time. Most people have experience with iterators already from working
    with filehandles. They are basically iterators hidden behind a somewhat
    odd syntax. This module gives you the same way of executing database
    queries.

    The trivial example at the start of the synopsis is not very different
    from using "fetchrow_hashref" in DBI directly to retrieve your database
    rows. But when we look at the second example we can start to see how it
    allows much cleaner separation of concerns without having to modify the
    core class (Person) to support iterators or database interaction at all.

    For more information about iterators and how they can work for you, have
    a look at chapter 4 in the book Higher-Order Perl mentioned below. It is
    free to download and highly recommended.

METHODS
  new($dbh)
    Creates a new iterator factory connected to the specified database
    handle.

  dbh
    Returns the database handle provided to new().

  prepare($query)
    Asks the database engine to parse the query and return a statement
    object that can be used to execute the query with optional parameters.

  query($query, @placeholder_values)
    Executes the query with the optional placeholder values. Returns a code
    reference you can execute until it is exhausted. If called in list
    context, it will also return a reference to the statement object itself.
    The iterator returns exactly what "fetchrow_hashref" in DBI returns.
    When the iterator is exhausted it will return undef.

SEE ALSO
    *   Higher-Order Perl by Mark Jason Dominus, page 163-173
        <http://hop.perl.plover.com/>

    *   Iterator

SEMANTIC VERSIONING
    This module uses semantic versioning concepts from <http://semver.org/>.

SUPPORT
  Perldoc
    You can find documentation for this module with the perldoc command.

      perldoc DBIx::Iterator

  Websites
    The following websites have more information about this module, and may
    be of help to you. As always, in addition to those websites please use
    your favorite search engine to discover more resources.

    *   MetaCPAN

        A modern, open-source CPAN search engine, useful to view POD in HTML
        format.

        <http://metacpan.org/release/DBIx-Iterator>

    *   Search CPAN

        The default CPAN search engine, useful to view POD in HTML format.

        <http://search.cpan.org/dist/DBIx-Iterator>

    *   RT: CPAN's Bug Tracker

        The RT ( Request Tracker ) website is the default bug/issue tracking
        system for CPAN.

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-Iterator>

    *   AnnoCPAN

        The AnnoCPAN is a website that allows community annotations of Perl
        module documentation.

        <http://annocpan.org/dist/DBIx-Iterator>

    *   CPAN Ratings

        The CPAN Ratings is a website that allows community ratings and
        reviews of Perl modules.

        <http://cpanratings.perl.org/d/DBIx-Iterator>

    *   CPAN Forum

        The CPAN Forum is a web forum for discussing Perl modules.

        <http://cpanforum.com/dist/DBIx-Iterator>

    *   CPANTS

        The CPANTS is a website that analyzes the Kwalitee ( code metrics )
        of a distribution.

        <http://cpants.perl.org/dist/overview/DBIx-Iterator>

    *   CPAN Testers

        The CPAN Testers is a network of smokers who run automated tests on
        uploaded CPAN distributions.

        <http://www.cpantesters.org/distro/D/DBIx-Iterator>

    *   CPAN Testers Matrix

        The CPAN Testers Matrix is a website that provides a visual overview
        of the test results for a distribution on various Perls/platforms.

        <http://matrix.cpantesters.org/?dist=DBIx-Iterator>

    *   CPAN Testers Dependencies

        The CPAN Testers Dependencies is a website that shows a chart of the
        test results of all dependencies for a distribution.

        <http://deps.cpantesters.org/?module=DBIx::Iterator>

  Bugs / Feature Requests
    Please report any bugs or feature requests by email to
    "bug-dbix-iterator at rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DBIx-Iterator>. You will
    be automatically notified of any progress on the request by the system.

  Source Code
    The code is open to the world, and available for you to hack on. Please
    feel free to browse it and play with it, or whatever. If you want to
    contribute patches, please send me a diff or prod me to pull from your
    repository :)

    <http://github.com/robinsmidsrod/DBIx-Iterator>

      git clone git://github.com/robinsmidsrod/DBIx-Iterator.git

AUTHOR
    Robin Smidsrød <robin@smidsrod.no>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Robin Smidsrød.

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