README
1NAME
2 DBIx::ContextualFetch - Add contextual fetches to DBI
3
4SYNOPSIS
5 my $dbh = DBI->connect(...., { RootClass => "DBIx::ContextualFetch" });
6
7 # Modified statement handle methods.
8 my $rv = $sth->execute;
9 my $rv = $sth->execute(@bind_values);
10 my $rv = $sth->execute(\@bind_values, \@bind_cols);
11
12 # In addition to the normal DBI sth methods...
13 my $row_ref = $sth->fetch;
14 my @row = $sth->fetch;
15
16 my $row_ref = $sth->fetch_hash;
17 my %row = $sth->fetch_hash;
18
19 my $rows_ref = $sth->fetchall;
20 my @rows = $sth->fetchall;
21
22 my $rows_ref = $sth->fetchall_hash;
23 my @tbl = $sth->fetchall_hash;
24
25DESCRIPTION
26 It always struck me odd that DBI didn't take much advantage of Perl's
27 context sensitivity. DBIx::ContextualFetch redefines some of the various
28 fetch methods to fix this oversight. It also adds a few new methods for
29 convenience (though not necessarily efficiency).
30
31SET-UP
32 my $dbh = DBIx::ContextualFetch->connect(@info);
33 my $dbh = DBI->connect(@info, { RootClass => "DBIx::ContextualFetch" });
34
35 To use this method, you can either make sure that everywhere you normall
36 call DBI->connect() you either call it on DBIx::ContextualFetch, or that
37 you pass this as your RootClass. After this DBI will Do The Right Thing
38 and pass all its calls through us.
39
40EXTENSIONS
41 execute
42 $rv = $sth->execute;
43 $rv = $sth->execute(@bind_values);
44 $rv = $sth->execute(\@bind_values, \@bind_cols);
45
46 execute() is enhanced slightly:
47
48 If called with no arguments, or with a simple list, execute() operates
49 normally. When when called with two array references, it performs the
50 functions of bind_param, execute and bind_columns similar to the
51 following:
52
53 $sth->execute(@bind_values);
54 $sth->bind_columns(undef, @bind_cols);
55
56 In addition, execute will accept tainted @bind_values. I can't think of
57 what a malicious user could do with a tainted bind value (in the general
58 case. Your application may vary.)
59
60 Thus a typical idiom would be:
61
62 $sth->execute([$this, $that], [\($foo, $bar)]);
63
64 Of course, this method provides no way of passing bind attributes
65 through to bind_param or bind_columns. If that is necessary, then you
66 must perform the bind_param, execute, bind_col sequence yourself.
67
68 fetch
69 $row_ref = $sth->fetch;
70 @row = $sth->fetch;
71
72 A context sensitive version of fetch(). When in scalar context, it will
73 act as fetchrow_arrayref. In list context it will use fetchrow_array.
74
75 fetch_hash
76 $row_ref = $sth->fetch_hash;
77 %row = $sth->fetch_hash;
78
79 A modification on fetchrow_hashref. When in scalar context, it acts just
80 as fetchrow_hashref() does. In list context it returns the complete
81 hash.
82
83 fetchall
84 $rows_ref = $sth->fetchall;
85 @rows = $sth->fetchall;
86
87 A modification on fetchall_arrayref. In scalar context it acts as
88 fetchall_arrayref. In list it returns an array of references to rows
89 fetched.
90
91 fetchall_hash
92 $rows_ref = $sth->fetchall_hash;
93 @rows = $sth->fetchall_hash;
94
95 A mating of fetchall_arrayref() with fetchrow_hashref(). It gets all
96 rows from the hash, each as hash references. In scalar context it
97 returns a reference to an array of hash references. In list context it
98 returns a list of hash references.
99
100ORIGINAL AUTHOR
101 Michael G Schwern as part of Ima::DBI
102
103CURRENT MAINTAINER
104 Tony Bowden <tony@tmtm.com>
105
106LICENSE
107 This library is free software; you can redistribute it and/or modify it
108 under the same terms as Perl itself.
109
110SEE ALSO
111 DBI. Ima::DBI. Class::DBI.
112
113