NAME

SQL::DB::Iter - SQL::DB database iterator

VERSION

0.971.2. Development release.

SYNOPSIS

  use SQL::DB::Iter;

  my $iter = SQL::DB::Iter->new(
      sth => $sth,
  );

  while (my $row = $iter->next) {
      print $row->column(), $row->some_other_column;
  }

  # Or if you want you can get everything at once:
  my @rows = $iter->all;

DESCRIPTION

SQL::DB::Iter is a class for traversing over records retrieved from a DBI statement handle. Note that this is a Perl-side iterator, completely unrelated to any database-side cursors.

The objects returned by the 'next' and 'all' methods are simple array-ref based objects with one accessor/modifer method per column. Method names are column names with spaces replaced by a '_'.

CONSTRUCTOR

new(sth => $sth)

Returns a new iterator object. $sth must be a DBI statement handle that has already been 'executed'.

ATTRIBUTES

sth -> DBI::st

The DBI statement handle. Read-only.

class -> Str

The class name into which retrieved rows are 'blessed'. This is automatically calculated based on the retrieved column names. Read-only.

METHODS

BUILD

Internal method.

next -> $row

Returns the next row from the statement handle as an object. Returns undef when there is no more data.

all -> @rows

Returns all remaining rows from the statement handle as a list of objects. Returns the empty list if no data is available.

object -> $obj

Returns the next row from the statement handle as an object. Returns undef when there is no more data.

objects -> @objects

Returns all remaining rows from the statement handle as a list of objects. Returns the empty list if no data is available.

hash -> $HashRef

Returns the next row from the statement handle as a reference to a hash. Returns undef when there is no more data.

hashes -> @HashRefs

Returns all remaining rows from the statement handle as a list of references to hashes. Returns the empty list if no data is available.

array -> $ArrayRef

Returns the next row from the statement handle as a reference to an array. Returns undef when there is no more data.

arrays -> @ArrayRefs

Returns all remaining rows from the statement handle as a list of references to arrays. Returns the empty list if no data is available.

finish

Calls finish() on the DBI statement handle and internally records that there is no more data to be retrieved. This method is automatically called when the iterator object goes out of scope, so be aware you cannot use the passed-in statement handle again.

SEE ALSO

DBI, SQL::DB

AUTHOR

Mark Lawrence <nomad@null.net>

COPYRIGHT AND LICENSE

Copyright (C) 2007-2011 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.