NAME
    DBIx::ContextualFetch - Add contextual fetches to DBI

SYNOPSIS
            my $dbh = DBI->connect(...., { RootClass => "DBIx::ContextualFetch" });

            # Modified statement handle methods.
            my $rv = $sth->execute;
            my $rv = $sth->execute(@bind_values);
            my $rv = $sth->execute(\@bind_values, \@bind_cols);

            # In addition to the normal DBI sth methods...
            my $row_ref = $sth->fetch;
            my @row     = $sth->fetch;

            my $row_ref = $sth->fetch_hash;
            my %row     = $sth->fetch_hash;

            my $rows_ref = $sth->fetchall;
            my @rows     = $sth->fetchall;

            my $rows_ref = $sth->fetchall_hash;
            my @tbl      = $sth->fetchall_hash;

DESCRIPTION
    It always struck me odd that DBI didn't take much advantage of Perl's
    context sensitivity. DBIx::ContextualFetch redefines some of the various
    fetch methods to fix this oversight. It also adds a few new methods for
    convenience (though not necessarily efficiency).

SET-UP
            my $dbh = DBIx::ContextualFetch->connect(@info);
            my $dbh = DBI->connect(@info, { RootClass => "DBIx::ContextualFetch" });

    To use this method, you can either make sure that everywhere you normall
    call DBI->connect() you either call it on DBIx::ContextualFetch, or that
    you pass this as your RootClass. After this DBI will Do The Right Thing
    and pass all its calls through us.

EXTENSIONS
  execute
            $rv = $sth->execute;
            $rv = $sth->execute(@bind_values);
            $rv = $sth->execute(\@bind_values, \@bind_cols);
 
    execute() is enhanced slightly:

    If called with no arguments, or with a simple list, execute() operates
    normally. When when called with two array references, it performs the
    functions of bind_param, execute and bind_columns similar to the
    following:

            $sth->execute(@bind_values);
            $sth->bind_columns(undef, @bind_cols);

    In addition, execute will accept tainted @bind_values. I can't think of
    what a malicious user could do with a tainted bind value (in the general
    case. Your application may vary.)

    Thus a typical idiom would be:

            $sth->execute([$this, $that], [\($foo, $bar)]);

    Of course, this method provides no way of passing bind attributes
    through to bind_param or bind_columns. If that is necessary, then you
    must perform the bind_param, execute, bind_col sequence yourself.

  fetch
            $row_ref = $sth->fetch;
            @row     = $sth->fetch;

    A context sensitive version of fetch(). When in scalar context, it will
    act as fetchrow_arrayref. In list context it will use fetchrow_array.

  fetch_hash
            $row_ref = $sth->fetch_hash;
            %row     = $sth->fetch_hash;

    A modification on fetchrow_hashref. When in scalar context, it acts just
    as fetchrow_hashref() does. In list context it returns the complete
    hash.

  fetchall
            $rows_ref = $sth->fetchall;
            @rows     = $sth->fetchall;

    A modification on fetchall_arrayref. In scalar context it acts as
    fetchall_arrayref. In list it returns an array of references to rows
    fetched.

  fetchall_hash
            $rows_ref = $sth->fetchall_hash;
            @rows     = $sth->fetchall_hash;

    A mating of fetchall_arrayref() with fetchrow_hashref(). It gets all
    rows from the hash, each as hash references. In scalar context it
    returns a reference to an array of hash references. In list context it
    returns a list of hash references.

ORIGINAL AUTHOR
    Michael G Schwern as part of Ima::DBI

CURRENT MAINTAINER
    Tony Bowden <tony@tmtm.com>

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

SEE ALSO
    DBI. Ima::DBI. Class::DBI.