r66227 - in /trunk/libdbix-simple-perl: ./ debian/ debian/source/ lib/DBIx/ lib/DBIx/Simple/ lib/DBIx/Simple/Result/ t/
jawnsy-guest at users.alioth.debian.org
jawnsy-guest at users.alioth.debian.org
Fri Dec 24 21:19:08 UTC 2010
Author: jawnsy-guest
Date: Fri Dec 24 21:18:58 2010
New Revision: 66227
URL: http://svn.debian.org/wsvn/pkg-perl/?sc=1&rev=66227
Log:
"Any OSI-Approved License"? Not sure of the DFSG-freeness here...
* New upstream release
* Use new 3.0 (quilt) source format
* Standards-Version 3.9.1 (no changes)
* Refresh copyright information
Added:
trunk/libdbix-simple-perl/debian/source/
trunk/libdbix-simple-perl/debian/source/format
trunk/libdbix-simple-perl/lib/DBIx/Simple/Result/
- copied from r66222, branches/upstream/libdbix-simple-perl/current/lib/DBIx/Simple/Result/
Modified:
trunk/libdbix-simple-perl/Changes
trunk/libdbix-simple-perl/MANIFEST
trunk/libdbix-simple-perl/META.yml
trunk/libdbix-simple-perl/README
trunk/libdbix-simple-perl/debian/changelog
trunk/libdbix-simple-perl/debian/control
trunk/libdbix-simple-perl/debian/copyright
trunk/libdbix-simple-perl/lib/DBIx/Simple.pm
trunk/libdbix-simple-perl/lib/DBIx/Simple/Comparison.pod
trunk/libdbix-simple-perl/lib/DBIx/Simple/Examples.pod
trunk/libdbix-simple-perl/t/sqlite.t
Modified: trunk/libdbix-simple-perl/Changes
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/Changes?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/Changes (original)
+++ trunk/libdbix-simple-perl/Changes Fri Dec 24 21:18:58 2010
@@ -2,12 +2,26 @@
Incompatible changes are marked with "!!". Incompatibility with and changes in
"undocumented features" are not always specifically mentioned here.
+
+1.34 Mon Dec 12 16:28 2010
+ - Added missing documentation. (Reported by Krassimir Berov.)
+ - Fixed off-by-20 mistake in unit tests.
+
+1.33 Sat Dec 4 0:30 2010
+ - New license: any(OSI).
+ - Documentation overhaul.
+ - New: $result->kv_list, $result->kv_array, $result->kv_flat,
+ $result->kv_arrays. Handy if the unordered nature of hashes gets in
+ the way.
+ - New: $result->object, $result->objects.
+ - Fixed bug #26924. Cache lookup missed statements at index 0.
+ (Reported by Stanis Trendelenburg via RT.)
+ - Please note that very probably RaiseError will be enabled by
+ default in the next version.
1.32 Mon Sep 17 14:58 2007
- Test updated to conform to fixed bug in Test::More. See
http://www.nntp.perl.org/group/perl.qa/2007/09/msg9269.html
- - Please note that very probably RaiseError will be enabled by
- default in the next version.
1.31 Sun Jul 15 0:29 2007
- New: $db->iquery. This method loads SQL::Interp on demand. The
@@ -18,9 +32,9 @@
1.30 Sun Apr 8 2:29 2007
- Fixed bug #18629. Apparently Want does not consider a method call in
rvalue context. The premature optimization that used Want has simply
- been removed. (Reported by Tomi via RT)
+ been removed. (Reported by Tomi via RT.)
- Fixed bug #22829. With connect($dbh) or new($dbh), DBIx::Simple no
- longer disconnects implicitly. (Reported by BORISZ via RT)
+ longer disconnects implicitly. (Reported by BORISZ via RT.)
1.29 Web Apr 4 2:22 2007
- Fixed documentation typo.
Modified: trunk/libdbix-simple-perl/MANIFEST
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/MANIFEST?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/MANIFEST (original)
+++ trunk/libdbix-simple-perl/MANIFEST Fri Dec 24 21:18:58 2010
@@ -9,4 +9,5 @@
lib/DBIx/Simple.pm
lib/DBIx/Simple/Examples.pod
lib/DBIx/Simple/Comparison.pod
+lib/DBIx/Simple/Result/RowObject.pm
META.yml Module meta-data (added by MakeMaker)
Modified: trunk/libdbix-simple-perl/META.yml
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/META.yml?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/META.yml (original)
+++ trunk/libdbix-simple-perl/META.yml Fri Dec 24 21:18:58 2010
@@ -1,11 +1,22 @@
-# http://module-build.sourceforge.net/META-spec.html
-#XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
-name: DBIx-Simple
-version: 1.32
-version_from: lib/DBIx/Simple.pm
-installdirs: site
+--- #YAML:1.0
+name: DBIx-Simple
+version: 1.34
+abstract: Very complete easy-to-use OO interface to DBI
+author:
+ - Juerd Waalboer <juerd at cpan.org>
+license: unknown
+distribution_type: module
+configure_requires:
+ ExtUtils::MakeMaker: 0
+build_requires:
+ ExtUtils::MakeMaker: 0
requires:
- DBI: 1.21
-
-distribution_type: module
-generated_by: ExtUtils::MakeMaker version 6.30_01
+ DBI: 1.21
+no_index:
+ directory:
+ - t
+ - inc
+generated_by: ExtUtils::MakeMaker version 6.55_02
+meta-spec:
+ url: http://module-build.sourceforge.net/META-spec-v1.4.html
+ version: 1.4
Modified: trunk/libdbix-simple-perl/README
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/README?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/README (original)
+++ trunk/libdbix-simple-perl/README Fri Dec 24 21:18:58 2010
@@ -23,4 +23,8 @@
Optionally, Text::Table can be used for added functionality.
+Optionally, Object::Accessor can be used for added functionality.
+
These modules are available from CPAN, <http://cpan.org/>.
+#
+#
Modified: trunk/libdbix-simple-perl/debian/changelog
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/debian/changelog?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/debian/changelog (original)
+++ trunk/libdbix-simple-perl/debian/changelog Fri Dec 24 21:18:58 2010
@@ -1,4 +1,12 @@
-libdbix-simple-perl (1.32-2) UNRELEASED; urgency=low
+libdbix-simple-perl (1.34-1) UNRELEASED; urgency=low
+
+ "Any OSI-Approved License"? Not sure of the DFSG-freeness here...
+
+ [ Jonathan Yu ]
+ * New upstream release
+ * Use new 3.0 (quilt) source format
+ * Standards-Version 3.9.1 (no changes)
+ * Refresh copyright information
[ Salvatore Bonaccorso ]
* debian/control: Changed: Replace versioned (build-)dependency on
@@ -8,7 +16,7 @@
[ Ryan Niebur ]
* Update jawnsy's email address
- -- Ryan Niebur <ryanryan52 at gmail.com> Tue, 01 Sep 2009 21:18:41 -0700
+ -- Jonathan Yu <jawnsy at cpan.org> Fri, 24 Dec 2010 16:17:32 -0500
libdbix-simple-perl (1.32-1) unstable; urgency=low
Modified: trunk/libdbix-simple-perl/debian/control
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/debian/control?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/debian/control (original)
+++ trunk/libdbix-simple-perl/debian/control Fri Dec 24 21:18:58 2010
@@ -6,7 +6,7 @@
libtest-pod-perl, libdbd-sqlite3-perl
Maintainer: Debian Perl Group <pkg-perl-maintainers at lists.alioth.debian.org>
Uploaders: Jonathan Yu <jawnsy at cpan.org>
-Standards-Version: 3.8.2
+Standards-Version: 3.9.1
Homepage: http://search.cpan.org/dist/DBIx-Simple/
Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libdbix-simple-perl/
Vcs-Browser: http://svn.debian.org/viewsvn/pkg-perl/trunk/libdbix-simple-perl/
Modified: trunk/libdbix-simple-perl/debian/copyright
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/debian/copyright?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/debian/copyright (original)
+++ trunk/libdbix-simple-perl/debian/copyright Fri Dec 24 21:18:58 2010
@@ -1,31 +1,33 @@
-Format-Specification:
- http://wiki.debian.org/Proposals/CopyrightFormat?action=recall&rev=196
-Upstream-Maintainer: Juerd Waalboer <juerd at cpan.org>
-Upstream-Source: http://search.cpan.org/dist/DBIx-Simple/
-Upstream-Name: DBIx-Simple
+Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
+Maintainer: Juerd Waalboer <juerd at cpan.org>
+Source: http://search.cpan.org/dist/DBIx-Simple/
+Name: DBIx-Simple
Files: *
+Copyright: Juerd Waalboer <juerd at cpan.org>
License: PD
Files: debian/*
-Copyright: 2009, Jonathan Yu <jawnsy at cpan.org>
-License: PD | Artistic | GPL-1+
+Copyright: 2009-2010, Jonathan Yu <jawnsy at cpan.org>
+License: PD or Artistic or GPL-1+
License: Artistic
- This program is free software; you can redistribute it and/or modify
- it under the terms of the Artistic License, which comes with Perl.
- On Debian GNU/Linux systems, the complete text of the Artistic License
- can be found in `/usr/share/common-licenses/Artistic'
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the Artistic License, which comes with Perl.
+ .
+ On Debian systems, the complete text of the Artistic License can be
+ found in `/usr/share/common-licenses/Artistic'.
License: GPL-1+
- 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 1, or (at your option)
- any later version.
- On Debian GNU/Linux systems, the complete text of the GNU General
- Public License can be found in `/usr/share/common-licenses/GPL'
+ 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 1, or (at your option)
+ any later version.
+ .
+ On Debian systems, the complete text of version 1 of the GNU General
+ Public License can be found in `/usr/share/common-licenses/GPL-1'.
License: PD
- There is no license. This software was released into the public
- domain. Do with it what you want, but on your own risk. The author
- disclaims any responsibility.
+ There is no license. This software was released into the public
+ domain. Do with it what you want, but on your own risk. The author
+ disclaims any responsibility.
Added: trunk/libdbix-simple-perl/debian/source/format
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/debian/source/format?rev=66227&op=file
==============================================================================
--- trunk/libdbix-simple-perl/debian/source/format (added)
+++ trunk/libdbix-simple-perl/debian/source/format Fri Dec 24 21:18:58 2010
@@ -1,0 +1,1 @@
+3.0 (quilt)
Modified: trunk/libdbix-simple-perl/lib/DBIx/Simple.pm
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/lib/DBIx/Simple.pm?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/lib/DBIx/Simple.pm (original)
+++ trunk/libdbix-simple-perl/lib/DBIx/Simple.pm Fri Dec 24 21:18:58 2010
@@ -3,7 +3,7 @@
use DBI;
use Carp ();
-$DBIx::Simple::VERSION = '1.32';
+$DBIx::Simple::VERSION = '1.34';
$Carp::Internal{$_} = 1
for qw(DBIx::Simple DBIx::Simple::Result DBIx::Simple::DeadObject);
@@ -75,6 +75,13 @@
require SQL::Abstract;
$_[0]->{abstract} ||= SQL::Abstract->new;
}
+
+sub error {
+ my ($self) = @_;
+ return 'DBI error: ' . (ref $self ? $self->{dbh}->errstr : $DBI::errstr);
+}
+
+sub dbh { $_[0]->{dbh} }
### private methods
@@ -134,7 +141,7 @@
my $old = $old_statements{$self};
- if (my $i = (grep $old->[$_][0] eq $query, 0..$#$old)[0]) {
+ if (defined( my $i = (grep $old->[$_][0] eq $query, 0..$#$old)[0] )) {
$st = splice(@$old, $i, 1)->[1];
$sth = $st->{sth};
} else {
@@ -172,12 +179,6 @@
return bless { st => $st, lc_columns => $self->{lc_columns} }, $self->{result_class};
}
-sub error {
- my ($self) = @_;
- return 'DBI error: ' . (ref $self ? $self->{dbh}->errstr : $DBI::errstr);
-}
-
-sub dbh { $_[0]->{dbh} }
sub begin_work { $_[0]->{dbh}->begin_work }
sub begin { $_[0]->begin_work }
sub commit { $_[0]->{dbh}->commit }
@@ -198,6 +199,7 @@
sub disconnect {
my ($self) = @_;
$self->_die(sprintf($err_cause, "$self->disconnect", (caller)[1, 2]));
+ return 1;
}
sub DESTROY {
@@ -337,6 +339,9 @@
$_[0]->{st}->{sth}->bind_columns(\@_[1..$#_]);
}
+
+### Single
+
sub fetch {
$_[0]->_die if ref $_[0]->{st} eq 'DBIx::Simple::DeadObject';
return $_[0]->{st}->{sth}->fetch;
@@ -368,6 +373,44 @@
);
}
+sub kv_list {
+ $_[0]->_die if ref $_[0]->{st} eq 'DBIx::Simple::DeadObject';
+ my @keys = $_[0]->columns;
+ my $values = $_[0]->array or return;
+ Carp::croak("Different numbers of column names and values")
+ if @keys != @$values;
+ return map { $keys[$_], $values->[$_] } 0 .. $#keys if wantarray;
+ return [ map { $keys[$_], $values->[$_] } 0 .. $#keys ];
+}
+
+sub kv_array {
+ $_[0]->_die if ref $_[0]->{st} eq 'DBIx::Simple::DeadObject';
+ scalar shift->kv_list(@_);
+}
+
+sub object {
+ $_[0]->_die if ref $_[0]->{st} eq 'DBIx::Simple::DeadObject';
+ my $self = shift;
+ my $class = shift || ':RowObject';
+ if ($class =~ /^:/) {
+ $class = "DBIx::Simple::Result:$class";
+ (my $package = "$class.pm") =~ s[::][/]g;
+ require $package;
+ }
+ if ($class->can('new_from_dbix_simple')) {
+ return scalar $class->new_from_dbix_simple($self, @_);
+ }
+ if ($class->can('new')) {
+ return $class->new( $self->kv_list );
+ }
+ Carp::croak(
+ qq(Can't locate object method "new_from_dbix_simple" or "new" ) .
+ qq(via package "$class" (perhaps you forgot to load "$class"?))
+ );
+}
+
+### Slurp
+
sub flat {
$_[0]->_die if ref $_[0]->{st} eq 'DBIx::Simple::DeadObject';
return map @$_, $_[0]->arrays if wantarray;
@@ -382,11 +425,47 @@
sub hashes {
$_[0]->_die if ref $_[0]->{st} eq 'DBIx::Simple::DeadObject';
- my ($self) = @_;
my @return;
my $dummy;
- push @return, $dummy while $dummy = $self->hash;
+ push @return, $dummy while $dummy = $_[0]->hash;
return wantarray ? @return : \@return;
+}
+
+sub kv_flat {
+ $_[0]->_die if ref $_[0]->{st} eq 'DBIx::Simple::DeadObject';
+ return map @$_, $_[0]->kv_arrays if wantarray;
+ return [ map @$_, $_[0]->kv_arrays ];
+}
+
+sub kv_arrays {
+ $_[0]->_die if ref $_[0]->{st} eq 'DBIx::Simple::DeadObject';
+ my @return;
+ my $dummy;
+ push @return, $dummy while $dummy = $_[0]->kv_array;
+ return wantarray ? @return : \@return;
+}
+
+sub objects {
+ $_[0]->_die if ref $_[0]->{st} eq 'DBIx::Simple::DeadObject';
+ my $self = shift;
+ my $class = shift || ':RowObject';
+ if ($class =~ /^:/) {
+ $class = "DBIx::Simple::Result:$class";
+ (my $package = "$class.pm") =~ s[::][/]g;
+ require $package;
+ }
+ if ($class->can('new_from_dbix_simple')) {
+ return $class->new_from_dbix_simple($self, @_) if wantarray;
+ return [ $class->new_from_dbix_simple($self, @_) ];
+ }
+ if ($class->can('new')) {
+ return map { $class->new( @$_ ) } $self->kv_arrays if wantarray;
+ return [ map { $class->new( @$_ ) } $self->kv_arrays ];
+ }
+ Carp::croak(
+ qq(Can't locate object method "new_from_dbix_simple" or "new" ) .
+ qq(via package "$class" (perhaps you forgot to load "$class"?))
+ );
}
sub map_hashes {
@@ -499,7 +578,7 @@
=head1 NAME
-DBIx::Simple - Easy-to-use OO interface to DBI
+DBIx::Simple - Very complete easy-to-use OO interface to DBI
=head1 SYNOPSIS
@@ -537,9 +616,12 @@
$result->into($foo, $bar, $baz)
$row = $result->fetch
- @row = $result->list @rows = $result->flat
- $row = $result->array @rows = $result->arrays
- $row = $result->hash @rows = $result->hashes
+ @row = $result->list @rows = $result->flat
+ $row = $result->array @rows = $result->arrays
+ $row = $result->hash @rows = $result->hashes
+ @row = $result->kv_list @rows = $result->kv_flat
+ $row = $result->kv_array @rows = $result->kv_arrays
+ $obj = $result->object @objs = $result->objects
%map = $result->map_arrays(...)
%map = $result->map_hashes(...)
@@ -579,15 +661,13 @@
=head2 DBIx::Simple methods
-=over 4
-
-=item C<< DBIx::Simple->connect($dbh) >>
-
-=item C<< DBIx::Simple->connect($dsn, $user, $pass, \%options) >>
-
-=item C<< DBIx::Simple->new($dbh) >>
-
-=item C<< DBIx::Simple->new($dsn, $user, $pass, \%options) >>
+=head3 Class methods
+
+=over 14
+
+=item C<connect($dbh)>, C<connect($dsn, $user, $pass, \%options)>
+
+=item C<new($dbh)>, C<new($dsn, $user, $pass, \%options)>
The C<connect> or C<new> class method takes either an existing DBI object
($dbh), or a list of arguments to pass to C<< DBI->connect >>. See L<DBI> for a
@@ -599,45 +679,15 @@
This method is the constructor and returns a DBIx::Simple object on success. On
failure, it returns undef.
-=item C<lc_columns = $bool>
-
-When true at time of query execution, makes C<columns>, C<hash>, C<hashes>, and
-C<map_hashes> use lower cased column names. C<lc_columns> is true by default.
-
-=item C<keep_statements = $integer>
-
-Sets the number of statement objects that DBIx::Simple can keep for reuse. This
-can dramatically speed up repeated queries (like when used in a loop).
-C<keep_statements> is 16 by default.
-
-A query is only reused if it equals a previously used one literally. This means
-that to benefit from this caching mechanism, you must use placeholders and
-never interpolate variables yourself.
-
- # Wrong:
- $db->query("INSERT INTO foo VALUES ('$foo', '$bar', '$baz')");
- $db->query("SELECT FROM foo WHERE foo = '$foo' OR bar = '$bar'");
-
- # Right:
- $db->query('INSERT INTO foo VALUES (??)', $foo, $bar, $baz);
- $db->query('SELECT FROM foo WHERE foo = ? OR bar = ?', $foo, $baz);
-
-Of course, automatic value escaping is a much better reason for using
-placeholders.
-
-=item C<result_class = $string>
-
-Class to use for result objects. Defaults to DBIx::Simple::Result. A
-constructor is not used.
-
-=item C<error>
-
-Returns the error string of the last DBI method. See the discussion of "C<err>"
-and "C<errstr>" in L<DBI>.
+=back
+
+=head3 Object methods
+
+=over 14
=item C<query($query, @values)>
-The C<query> method prepares and executes the query and returns a result object.
+Prepares and executes the query and returns a result object.
If the string C<(??)> is present in the query, it is replaced with a list of as
many question marks as @values.
@@ -647,43 +697,26 @@
them. You should always use placeholders, and never use raw user input in
database queries.
-On success, returns a DBIx::Simple::Result object.
-
-On failure, returns a DBIx::Simple::Dummy object.
-
-=item C<iquery>
+On success, returns a DBIx::Simple::Result object. On failure, returns a
+DBIx::Simple::Dummy object.
+
+=item C<iquery(...)>
Uses SQL::Interp to interpolate values into a query, and uses the resulting
-generated query and bind arguments with C<query>.
-
-See SQL::Interp's documentation for usage information.
-
-I<Requires that Mark Stosberg's SQL::Interp module be installed. It is
-available from CPAN. SQL::Interp is a fork from David Manura's
-SQL::Interpolate.>
+generated query and bind arguments with C<query>. See SQL::Interp's
+documentation for usage information.
+
+Requires Mark Storberg's SQL::Interp, which is available from CPAN. SQL::Interp
+is a fork from David Manura's SQL::Interpolate.
=item C<select>, C<insert>, C<update>, C<delete>
Calls the respective method on C<abstract>, and uses the resulting generated
-query and bind arguments with C<query>.
-
-See SQL::Abstract's documentation for usage information. You can override the
-object by assigning to the C<abstract> property.
-
-Obviously, calling C<query> directly is faster for the computer and using these
-abstracting methods is faster for the programmer.
-
-=item C<< abstract = SQL::Abstract->new(...) >>
-
-Sets the object to use with the C<select>, C<insert>, C<update> and C<delete>
-methods. On first access, will create one with SQL::Abstract's default options.
-
-I<Requires that Nathan Wiger's SQL::Abstract module be installed. It is
-available from CPAN.>
-
-In theory, you can assign any object to this property, as long as that object
-has these four methods, and they return a list suitable for use with the
-C<query> method.
+query and bind arguments with C<query>. See SQL::Abstract's documentation for
+usage information. You can override the object by assigning to the C<abstract>
+property.
+
+Requires Nathan Wiger's SQL::Abstract, which is available from CPAN.
=item C<begin_work>, C<begin>, C<commit>, C<rollback>
@@ -694,18 +727,12 @@
=item C<func(...)>
-This calls the C<func> method of DBI. See L<DBI> for details.
+Calls the C<func> method of DBI. See L<DBI> for details.
=item C<last_insert_id(...)>
-This calls the C<last_insert_id> method of DBI. See L<DBI> for details. Note
-that this feature requires DBI 1.38 or newer.
-
-=item C<dbh>
-
-Exposes the internal database handle. Use this only if you know what you are
-doing. Keeping a reference or doing queries can interfere with DBIx::Simple's
-garbage collection and error reporting.
+Calls the C<last_insert_id> method of DBI. See L<DBI> for details. Note that
+this feature requires DBI 1.38 or newer.
=item C<disconnect>
@@ -716,6 +743,65 @@
=back
+=head3 Object properties
+
+=over 14
+
+=item C<dbh>
+
+Exposes the internal database handle. Use this only if you know what you are
+doing. Keeping a reference or doing queries can interfere with DBIx::Simple's
+garbage collection and error reporting.
+
+=item C<lc_columns = $bool>
+
+When true at time of query execution, makes several result object methods use
+lower cased column names. C<lc_columns> is true by default.
+
+=item C<keep_statements = $integer>
+
+Sets the number of statement objects that DBIx::Simple can keep for reuse. This
+can dramatically speed up repeated queries (like when used in a loop).
+C<keep_statements> is 16 by default.
+
+A query is only reused if it equals a previously used one literally. This means
+that to benefit from this caching mechanism, you must use placeholders and
+never interpolate variables yourself.
+
+ # Wrong:
+ $db->query("INSERT INTO foo VALUES ('$foo', '$bar', '$baz')");
+ $db->query("SELECT FROM foo WHERE foo = '$foo' OR bar = '$bar'");
+
+ # Right:
+ $db->query('INSERT INTO foo VALUES (??)', $foo, $bar, $baz);
+ $db->query('SELECT FROM foo WHERE foo = ? OR bar = ?', $foo, $baz);
+
+Of course, automatic value escaping is a much better reason for using
+placeholders.
+
+=item C<result_class = $string>
+
+Class to use for result objects. Defaults to DBIx::Simple::Result. A
+constructor is not used.
+
+=item C<error>
+
+Returns the error string of the last DBI method. See the discussion of "C<err>"
+and "C<errstr>" in L<DBI>.
+
+=item C<< abstract = SQL::Abstract->new(...) >>
+
+Sets the object to use with the C<select>, C<insert>, C<update> and C<delete>
+methods. On first access, will create one with SQL::Abstract's default options.
+
+Requires Nathan Wiger's SQL::Abstract, which is available from CPAN.
+
+In theory, you can assign any object to this property, as long as that object
+has these four methods, and they return a list suitable for use with the
+C<query> method.
+
+=back
+
=head2 DBIx::Simple::Dummy
The C<query> method of DBIx::Simple returns a dummy object on failure. Its
@@ -724,102 +810,30 @@
=head2 DBIx::Simple::Result methods
-=over 12
+Methods documented to return "a list" return a reference to an array of the
+same in scalar context, unless something else is explicitly mentioned.
+
+=over 14
=item C<columns>
-Returns a list of column names. In scalar context, returns an array reference.
-
-Column names are lower cased if C<lc_columns> was true when the query was
-executed.
+Returns a list of column names. Affected by C<lc_columns>.
=item C<bind(LIST)>
-Binds the given LIST to the columns. The elements of LIST must be writable
-LVALUEs. In other words, use this method as:
-
- $result->bind(my ($foo, $bar));
- $result->fetch;
-
-Or, combined:
-
- $result->into(my ($foo, $bar));
-
-Unlike with DBI's C<bind_columns>, the C<\> operator is not needed.
+Binds the given LIST of variables to the columns. Unlike with DBI's
+C<bind_columns>, passing references is not needed.
Bound variables are very efficient. Binding a tied variable doesn't work.
-=item C<fetch>
-
-Fetches a single row and returns a reference to the array that holds the
-values. This is the same array every time.
-
-Subsequent fetches (using any method) may change the values in the variables
-passed and the returned reference's array.
-
-=item C<into(LIST)>
-
-Combines C<bind> with C<fetch>. Returns what C<fetch> returns.
-
-=item C<list>
-
-Fetches a single row and returns a list of values. In scalar context,
-returns only the last value.
-
-=item C<array>
-
-Fetches a single row and returns an array reference.
-
-=item C<hash>
-
-Fetches a single row and returns a hash reference.
-
-Keys are lower cased if C<lc_columns> was true when the query was executed.
-
-=item C<flat>
-
-Fetches all remaining rows and returns a flattened list.
-
-In scalar context, returns an array reference.
-
-=item C<arrays>
-
-Fetches all remaining rows and returns a list of array references.
-
-In scalar context, returns an array reference.
-
-=item C<hashes>
-
-Fetches all remaining rows and returns a list of hash references.
-
-In scalar context, returns an array reference.
-
-Keys are lower cased if C<lc_columns> was true when the query was executed.
-
-=item C<map_arrays($column_number)>
-
-Constructs a hash of array references keyed by the values in the chosen column.
-
-In scalar context, returns a hash reference.
-
-In list context, returns interleaved keys and values.
-
-=item C<map_hashes($column_name)>
-
-Constructs a hash of hash references keyed by the values in the chosen column.
-
-In scalar context, returns a hash reference.
-
-In list context, returns interleaved keys and values.
-
-=item C<map>
-
-Constructs a simple hash, using the two columns as key/value pairs. Should
-only be used with queries that return two columns.
-
-In scalar context, returns a hash reference.
-
-In list context, returns interleaved keys and values.
+=item C<attr(...)>
+
+Returns a copy of an sth attribute (property). See L<DBI/"Statement Handle
+Attributes"> for details.
+
+=item C<func(...)>
+
+This calls the C<func> method on the sth of DBI. See L<DBI> for details.
=item C<rows>
@@ -830,26 +844,129 @@
returned. MySQL does provide this information. See L<DBI> for a detailed
explanation.
+=item C<finish>
+
+Finishes the statement. After finishing a statement, it can no longer be used.
+When the result object is destroyed, its statement handle is automatically
+finished and destroyed. There should be no reason to call this method
+explicitly; just let the result object go out of scope.
+
+=back
+
+=head3 Fetching a single row at a time
+
+=over 14
+
+=item C<fetch>
+
+Returns a reference to the array that holds the values. This is the same array
+every time.
+
+Subsequent fetches (using any method) may change the values in the variables
+passed and the returned reference's array.
+
+=item C<into(LIST)>
+
+Combines C<bind> with C<fetch>. Returns what C<fetch> returns.
+
+=item C<list>
+
+Returns a list of values, or (in scalar context), only the last value.
+
+=item C<array>
+
+Returns a reference to an array.
+
+=item C<hash>
+
+Returns a reference to a hash, keyed by column name. Affected by C<lc_columns>.
+
+=item C<kv_list>
+
+Returns an ordered list of interleaved keys and values. Affected by
+C<lc_columns>.
+
+=item C<kv_array>
+
+Returns a reference to an array of interleaved column names and values. Like
+kv, but returns an array reference even in list context. Affected by
+C<lc_columns>.
+
+=item C<object($class, ...)>
+
+Returns an instance of $class. See "Object construction". Possibly affected by
+C<lc_columns>.
+
+=back
+
+=head3 Fetching all remaining rows
+
+=over 14
+
+=item C<flat>
+
+Returns a flattened list.
+
+=item C<arrays>
+
+Returns a list of references to arrays
+
+=item C<hashes>
+
+Returns a list of references to hashes, keyed by column name. Affected by
+C<lc_columns>.
+
+=item C<kv_flat>
+
+Returns an flattened list of interleaved column names and values. Affected by
+C<lc_columns>.
+
+=item C<kv_arrays>
+
+Returns a list of references to arrays of interleaved column names and values.
+Affected by C<lc_columns>.
+
+=item C<objects($class, ...)>
+
+Returns a list of instances of $class. See "Object construction". Possibly
+affected by C<lc_columns>.
+
+=item C<map_arrays($column_number)>
+
+Constructs a hash of array references keyed by the values in the chosen column,
+and returns a list of interleaved keys and values, or (in scalar context), a
+reference to a hash.
+
+=item C<map_hashes($column_name)>
+
+Constructs a hash of hash references keyed by the values in the chosen column,
+and returns a list of interleaved keys and values, or (in scalar context), a
+reference to a hash. Affected by C<lc_columns>.
+
+=item C<map>
+
+Constructs a simple hash, using the two columns as key/value pairs. Should
+only be used with queries that return two columns. Returns a list of interleaved
+keys and values, or (in scalar context), a reference to a hash.
+
=item C<xto(%attr)>
Returns a DBIx::XHTML_Table object, passing the constructor a reference to
C<%attr>.
-I<Requires that Jeffrey Hayes Anderson's DBIx::XHTML_Table module be installed.
-It is available from CPAN.>
+Requires Jeffrey Hayes Anderson's DBIx::XHTML_Table, which is available from
+CPAN.
In general, using the C<html> method (described below) is much easier. C<xto>
-is available in case you need more flexibility.
-
-This method ignores the C<lc_columns> property.
+is available in case you need more flexibility. Not affected by C<lc_columns>.
=item C<html(%attr)>
Returns an (X)HTML formatted table, using the DBIx::XHTML_Table module. Passes
a reference to C<%attr> to both the constructor and the C<output> method.
-I<Requires that Jeffrey Hayes Anderson's DBIx::XHTML_Table module be installed.
-It is available from CPAN.>
+Requires Jeffrey Hayes Anderson's DBIx::XHTML_Table, which is available from
+CPAN.
This method is a shortcut method. That means that
@@ -874,29 +991,78 @@
Returns a string with a simple text representation of the data. C<$type>
can be any of: C<neat>, C<table>, C<box>. It defaults to C<table> if
-Text::Table is installed, to C<neat> if it is.
-
-I<C<table> and C<box> require that Anno Siegel's Text::Table module be
-installed. It is available from CPAN.>
-
-
-=item C<attr(...)>
-
-Returns a copy of an sth attribute (property). See L<DBI/"Statement Handle
-Attributes"> for details.
-
-=item C<func(...)>
-
-This calls the C<func> method of DBI. See L<DBI> for details.
-
-=item C<finish>
-
-Finishes the statement. After finishing a statement, it can no longer be used.
-When the result object is destroyed, its statement handle is automatically
-finished and destroyed. There should be no reason to call this method
-explicitly; just let the result object go out of scope.
+Text::Table is installed, to C<neat> if it isn't.
+
+C<table> and C<box> require Anno Siegel's Text::Table, which is available from
+CPAN.
=back
+
+=head2 Object construction
+
+DBIx::Simple has basic support for returning results as objects. The actual
+construction method has to be provided by the chosen class, making this
+functionality rather advanced and perhaps unsuited for beginning programmers.
+
+When the C<object> or C<objects> method is called on the result object returned
+by one of the query methods, two approaches are tried. In either case, pass the
+name of a class as the first argument. A prefix of a single colon can be used
+as an alias for C<DBIx::Simple::Result::>, e.g. C<":Example"> is short for
+C<"DBIx::Simple::Result::Example">. When this shortcut is used, the
+corresponding module is loaded automatically.
+
+The default class when no class is given, is C<:RowObject>. It requires Jos
+Boumans' Object::Accessor, which is available from CPAN.
+
+=head3 Simple object construction
+
+When C<object> is given a class that provides a C<new> method, but not a
+C<new_from_dbix_simple> method, C<new> is called with a list of interleaved
+column names and values, like a flattened hash, but ordered. C<objects> causes
+C<new> to be called multiple times, once for each remaining row.
+
+Example:
+
+ {
+ package DBIx::Simple::Result::ObjectExample;
+ sub new {
+ my ($class, %args) = @_;
+ return bless $class, \%args;
+ }
+
+ sub foo { ... }
+ sub bar { ... }
+ }
+
+
+ $db->query('SELECT foo, bar FROM baz')->object(':ObjectExample')->foo();
+
+=head3 Advanced object construction
+
+When C<object> or C<objects> is given a class that provides a
+C<new_from_dbix_simple> method, any C<new> is ignored, and
+C<new_from_dbix_simple> is called with a list of the DBIx::Simple::Result
+object and any arguments passed to C<object> or C<objects>.
+
+C<new_from_dbix_simple> is called in scalar context for C<object>, and in list
+context for C<objects>. In scalar context, it should fetch I<exactly one row>,
+and in list context, it should fetch I<all remaining rows>.
+
+Example:
+
+ {
+ package DBIx::Simple::Result::ObjectExample;
+ sub new_from_dbix_simple {
+ my ($class, $result, @args) = @_;
+ return map { bless $class, $_ } $result->hashes if wantarray;
+ return bless $class, $result->hash;
+ }
+
+ sub foo { ... }
+ sub bar { ... }
+ }
+
+ $db->query('SELECT foo, bar FROM baz')->object(':ObjectExample')->foo();
=head1 MISCELLANEOUS
@@ -908,13 +1074,13 @@
=head1 LICENSE
-There is no license. This software was released into the public domain. Do with
-it what you want, but on your own risk. The author disclaims any
-responsibility.
+Pick your favourite OSI approved license :)
+
+http://www.opensource.org/licenses/alphabetical
=head1 AUTHOR
-Juerd Waalboer <juerd at cpan.org> <http://juerd.nl/>
+Juerd Waalboer <#####@juerd.nl> <http://juerd.nl/>
=head1 SEE ALSO
Modified: trunk/libdbix-simple-perl/lib/DBIx/Simple/Comparison.pod
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/lib/DBIx/Simple/Comparison.pod?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/lib/DBIx/Simple/Comparison.pod (original)
+++ trunk/libdbix-simple-perl/lib/DBIx/Simple/Comparison.pod Fri Dec 24 21:18:58 2010
@@ -114,12 +114,6 @@
map_arrays
map
-=head1 LICENSE
-
-There is no license. This software was released into the public domain. Do with
-it what you want, but on your own risk. The author disclaims any
-responsibility.
-
=head1 AUTHOR
Juerd Waalboer <juerd at cpan.org> <http://juerd.nl/>
Modified: trunk/libdbix-simple-perl/lib/DBIx/Simple/Examples.pod
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/lib/DBIx/Simple/Examples.pod?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/lib/DBIx/Simple/Examples.pod (original)
+++ trunk/libdbix-simple-perl/lib/DBIx/Simple/Examples.pod Fri Dec 24 21:18:58 2010
@@ -373,12 +373,6 @@
For C<table> and C<box>, you need Anno Siegel's Text::Table module installed.
-=head1 LICENSE
-
-There is no license. This software was released into the public domain. Do with
-it what you want, but on your own risk. The author disclaims any
-responsibility.
-
=head1 AUTHOR
Juerd Waalboer <juerd at cpan.org> <http://juerd.nl/>
Modified: trunk/libdbix-simple-perl/t/sqlite.t
URL: http://svn.debian.org/wsvn/pkg-perl/trunk/libdbix-simple-perl/t/sqlite.t?rev=66227&op=diff
==============================================================================
--- trunk/libdbix-simple-perl/t/sqlite.t (original)
+++ trunk/libdbix-simple-perl/t/sqlite.t Fri Dec 24 21:18:58 2010
@@ -1,4 +1,5 @@
use Test::More;
+use strict;
BEGIN {
eval { require DBD::SQLite; 1 }
@@ -6,7 +7,7 @@
eval { DBD::SQLite->VERSION >= 1 }
or plan skip_all => 'DBD::SQLite >= 1.00 required';
- plan tests => 27;
+ plan tests => 56;
use_ok('DBIx::Simple');
}
@@ -36,6 +37,7 @@
is_deeply([ $db->query($q)->list ], [ qw(a b c) ]);
+
is_deeply($db->query($q)->array, [ qw(a b c) ]);
is_deeply(scalar $db->query($q)->arrays, [ [ qw(a b c) ], [ qw(d e f) ], [ qw(g (??) h) ] ]);
@@ -44,10 +46,21 @@
is_deeply(scalar $db->query($q)->hashes, [ { qw(foo a bar b baz c) }, { qw(foo d bar e baz f) }, { qw(foo g bar (??) baz h) } ]);
+is_deeply([ $db->query($q)->kv_list ], [ qw(foo a bar b baz c) ]);
+is_deeply(scalar
+ $db->query($q)->kv_list, [ qw(foo a bar b baz c) ]);
+is_deeply( $db->query($q)->kv_array , [ qw(foo a bar b baz c) ]);
+
+
+is_deeply(scalar $db->query($q)->kv_arrays, [ [ qw(foo a bar b baz c) ], [ qw(foo d bar e baz f) ], [ qw(foo g bar (??) baz h) ] ]);
+is_deeply(scalar $db->query($q)->kv_flat, [ qw( foo a bar b baz c foo d bar e baz f foo g bar (??) baz h) ]);
+
is_deeply(scalar $db->query($q)->columns, [ qw(foo bar baz) ]);
is_deeply([ $db->query($q)->arrays ], scalar $db->query($q)->arrays);
is_deeply([ $db->query($q)->hashes ], scalar $db->query($q)->hashes);
+is_deeply([ $db->query($q)->kv_flat ], scalar $db->query($q)->kv_flat);
+is_deeply([ $db->query($q)->kv_arrays ], scalar $db->query($q)->kv_arrays);
is_deeply([ $db->query($q)->columns ], scalar $db->query($q)->columns);
is_deeply(scalar $db->query($q)->map_arrays(2), { c => [ qw(a b) ], f => [ qw(d e) ], h => [ qw(g (??)) ] });
@@ -71,3 +84,36 @@
my $c = 'c';
is_deeply(scalar $db->iquery('SELECT * FROM xyzzy WHERE baz =', \$c)->array, [ qw(a b c) ]);
}
+
+SKIP: {
+ eval { require Object::Accessor } or skip "Object::Accessor required", 21;
+
+ my $object = $db->query($q)->object;
+ isa_ok($object, "DBIx::Simple::Result::RowObject");
+ is($object->foo, 'a');
+ is($object->bar, 'b', 'bar is b');
+ is($object->baz, 'c');
+
+ my @objects = $db->query($q)->objects;
+ isa_ok($objects[0], "DBIx::Simple::Result::RowObject");
+ is($objects[0]->foo, 'a');
+ is($objects[0]->bar, 'b');
+ is($objects[0]->baz, 'c');
+ isa_ok($objects[1], "DBIx::Simple::Result::RowObject");
+ is($objects[1]->foo, 'd');
+ is($objects[1]->bar, 'e');
+ is($objects[1]->baz, 'f');
+
+ sub Mock::new_from_dbix_simple {
+ my ($class, $result, @foo) = @_;
+ isa_ok($result, "DBIx::Simple::Result");
+ is_deeply(\@foo, [ 42, 21 ]);
+ return wantarray;
+ }
+
+ ok(! $db->query($q)->object('Mock', 42, 21)); # wantarray false
+ is_deeply( [ $db->query($q)->objects('Mock', 42, 21) ], [ 1 ]); # wantarray true
+ is_deeply(scalar $db->query($q)->objects('Mock', 42, 21), [ 1 ]); # wantarray true
+}
+
+ok($db->disconnect);
More information about the Pkg-perl-cvs-commits
mailing list