[Rt-commit] [svn] r1886 - in DBIx-SearchBuilder/trunk: .
SearchBuilder SearchBuilder/Handle SearchBuilder/Record
jesse at pallas.eruditorum.org
jesse at pallas.eruditorum.org
Sat Nov 13 20:25:07 EST 2004
Author: jesse
Date: Sat Nov 13 20:25:06 2004
New Revision: 1886
Modified:
DBIx-SearchBuilder/trunk/ (props changed)
DBIx-SearchBuilder/trunk/Changes
DBIx-SearchBuilder/trunk/SearchBuilder.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Handle.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Informix.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Handle/ODBC.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Oracle.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Pg.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Handle/SQLite.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Sybase.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Handle/mysql.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Handle/mysqlPP.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Record.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Record/Cachable.pm
Log:
r9233 at tinbook: jesse | 2004-11-14T01:24:40.108759Z
Date: Fri, 12 Nov 2004 20:58:15 -0500
Subject: Re: search.cpan.org: DBIx-SearchBuilder-1.13_04
From: Matthew Simon Cavalletto <simonm at cavalletto.org>
To: Jesse <jesse at fsck.com>
Message-Id: <7BA889F7-3517-11D9-91E5-003065AFEA5E at cavalletto.org>
Most of it is just rearrangement of the POD documentation and a few
small editorial suggestions.
I've also made a few tweaks to the ::Record class to eliminate the
hard-coding of the name of the id column. The tests still pass, but you
might need to review these more carefully than the POD changes to make
sure I'm not going to break RT or something...
Modified: DBIx-SearchBuilder/trunk/Changes
==============================================================================
--- DBIx-SearchBuilder/trunk/Changes (original)
+++ DBIx-SearchBuilder/trunk/Changes Sat Nov 13 20:25:06 2004
@@ -15,7 +15,9 @@
types in the database as mysql generally does. Additionally, it truncates
things at utf8 character boundaries...as mysql does not.
- Fix for an undefined record cache warning on load from Autrijus Tang
-
+ - Major documentation cleanups --Simon Cavalletto
+ - A few tweaks to the ::Record class to eliminate the
+ hard-coding of the name of the id column --Simon Cavalletto
1.12
- Better error handling for some query build failure cases
Modified: DBIx-SearchBuilder/trunk/SearchBuilder.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder.pm Sat Nov 13 20:25:06 2004
@@ -15,11 +15,23 @@
use DBIx::SearchBuilder;
- ...
+ use DBIx::SearchBuilder::Handle;
+ my $handle = DBIx::SearchBuilder::Handle->new();
+ $handle->Connect( Driver => 'SQLite', Database => "my_test_db" );
+
+ my $sb = DBIx::SearchBuilder->new( Handle => $handle, Table => "my_table" );
+
+ $sb->Limit( FIELD => "column_1", VALUE => "matchstring" );
+
+ while ( my $record = $sb->Next ) {
+ print $record->my_column_name();
+ }
=head1 DESCRIPTION
+This module provides an object-oriented mechanism for retrieving and updating data in a DBI-accesible database.
+=head1 METHODS
=cut
@@ -95,7 +107,7 @@
=head2 _Handle [DBH]
-Get or set this object's DBI database handle.
+Get or set this object's DBIx::SearchBuilder::Handle object.
=cut
@@ -138,7 +150,7 @@
=head2 AddRecord RECORD
- Adds a record object to this collection
+Adds a record object to this collection
=cut
@@ -283,6 +295,13 @@
# }}}
# {{{ sub _isLimited
+
+=head2 _isLimited
+
+If we've limited down this search, return true. Otherwise, return false.
+
+=cut
+
sub _isLimited {
my $self = shift;
if (@_) {
@@ -301,8 +320,7 @@
=head2 BuildSelectQuery
-Builds a query string for a "SELECT rows from Tables" statement for this SB
-object
+Builds a query string for a "SELECT rows from Tables" statement for this SearchBuilder object
=cut
@@ -336,7 +354,7 @@
=head2 BuildSelectCountQuery
-Builds a SELECT statement to find the number of rows this SB object would find.
+Builds a SELECT statement to find the number of rows this SearchBuilder object would find.
=cut
@@ -403,7 +421,7 @@
=head2 GotoFirstItem
-Starts the recordset counter over from the first item. the next time you call Next,
+Starts the recordset counter over from the first item. The next time you call Next,
you'll get the first item returned by the database, as if you'd just started iterating
through the result set.
@@ -498,7 +516,7 @@
=head2 NewItem
- NewItem must be subclassed. It is used by DBIx::SearchBuilder to create record
+NewItem must be subclassed. It is used by DBIx::SearchBuilder to create record
objects for each row returned from the database.
=cut
@@ -550,32 +568,66 @@
=head2 Limit
-Limit takes a paramhash.
+Limit takes a hash of parameters with the following keys:
+
+=over 4
+
+=item TABLE
+
+Can be set to something different than this table if a join is
+wanted (that means we can't do recursive joins as for now).
+
+=item ALIAS
+
+Unless ALIAS is set, the join criterias will be taken from EXT_LINKFIELD
+and INT_LINKFIELD and added to the criterias. If ALIAS is set, new
+criterias about the foreign table will be added.
+
+=item FIELD
+
+Column to be checked against.
+
+=item VALUE
-# TABLE can be set to something different than this table if a join is
-# wanted (that means we can't do recursive joins as for now). Unless
+Should always be set and will always be quoted.
-# ALIAS is set, the join criterias will be taken from EXT_LINKFIELD
-# and INT_LINKFIELD and added to the criterias. If ALIAS is set, new
-# criterias about the foreign table will be added.
+=item OPERATOR
-# VALUE should always be set and will always be quoted.
+OPERATOR is the SQL operator to use for this phrase. Possible choices include:
-# ENTRYAGGREGATOR can be AND or OR (or anything else valid to aggregate two
-clauses in SQL
+=over 4
-OPERATOR is the SQL operator to use for this phrase. =, !=, LIKE. NOT LIKE
-In the case of LIKE, the string ins surrounded in % signs. Yes. this is a bug.
+=item "="
+
+=item "!="
+
+=item "LIKE"
+
+In the case of LIKE, the string is surrounded in % signs. Yes. this is a bug.
+
+=item "NOT LIKE"
+
+=item "STARTSWITH"
STARTSWITH is like LIKE, except it only appends a % at the end of the string
+=item "ENDSWITH"
+
ENDSWITH is like LIKE, except it prepends a % to the beginning of the string
+=back
+
+=item ENTRYAGGREGATOR
+
+Can be AND or OR (or anything else valid to aggregate two clauses in SQL)
+=item CASESENSITIVE
on some databases, such as postgres, setting CASESENSITIVE to 1 will make
this search case sensitive
+=back
+
=cut
sub Limit {
@@ -1002,14 +1054,12 @@
=head2 GroupBy
-OBSOLUTE. You want GroupByCols
+Alias for the GroupByCols method.
=cut
-sub GroupBy {
- my $self = shift;
- $self->GroupByCols( @_);
-}
+sub GroupBy { (shift)->GroupByCols( @_) }
+
# }}}
# {{{ GroupByCols
@@ -1057,7 +1107,6 @@
Private function to return the "GROUP BY" clause for this query.
-
=cut
sub _GroupClause {
@@ -1126,7 +1175,6 @@
Join instructs DBIx::SearchBuilder to join two tables.
-
The standard form takes a param hash with keys ALIAS1, FIELD1, ALIAS2 and
FIELD2. ALIAS1 and ALIAS2 are column aliases obtained from $self->NewAlias or
a $self->Limit. FIELD1 and FIELD2 are the fields in ALIAS1 and ALIAS2 that
@@ -1346,7 +1394,6 @@
# 22:32 [msg(Robrt)] since I'm not convinced it's been doing that correctly
-
sub CountAll {
my $self = shift;
@@ -1560,7 +1607,6 @@
-
=head1 AUTHOR
Copyright (c) 2001-2004 Jesse Vincent, jesse at fsck.com.
@@ -1573,7 +1619,7 @@
=head1 SEE ALSO
-DBIx::SearchBuilder::Handle, DBIx::SearchBuilder::Record, perl(1).
+DBIx::SearchBuilder::Handle, DBIx::SearchBuilder::Record.
=cut
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Handle.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Handle.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Handle.pm Sat Nov 13 20:25:06 2004
@@ -6,7 +6,6 @@
use Class::ReturnValue;
use vars qw($VERSION @ISA %DBIHandle $PrevHandle $DEBUG $TRANSDEPTH);
-
$TRANSDEPTH = 0;
$VERSION = '$Version$';
@@ -22,24 +21,16 @@
use DBIx::SearchBuilder::Handle;
- my $Handle = DBIx::SearchBuilder::Handle->new();
- $Handle->Connect( Driver => 'mysql',
- Database => 'dbname',
- Host => 'hostname',
- User => 'dbuser',
- Password => 'dbpassword');
-
+ my $handle = DBIx::SearchBuilder::Handle->new();
+ $handle->Connect( Driver => 'mysql',
+ Database => 'dbname',
+ Host => 'hostname',
+ User => 'dbuser',
+ Password => 'dbpassword');
-
=head1 DESCRIPTION
-Jesse's a slacker.
-
-Blah blah blah.
-
-=head1 AUTHOR
-
-Jesse Vincent, jesse at fsck.com
+This class provides a wrapper for DBI handles that can also perform a number of additional functions.
=cut
@@ -65,35 +56,6 @@
# }}}
-# {{{ sub Insert
-=head2 Insert $TABLE_NAME @KEY_VALUE_PAIRS
-
-Takes a table name and a set of key-value pairs in an array. splits the key value pairs, constructs an INSERT statement and performs the insert. Returns the row_id of this row.
-
-=cut
-
-sub Insert {
- my($self, $table, @pairs) = @_;
- my(@cols, @vals, @bind);
-
-# my %seen; #only the *first* value is used - allows drivers to specify default
- while ( my $key = shift @pairs ) {
- my $value = shift @pairs;
- # next if $seen{$key}++;
- push @cols, $key;
- push @vals, '?';
- push @bind, $value;
- }
-
- my $QueryString =
- "INSERT INTO $table (". join(", ", @cols). ") VALUES ".
- "(". join(", ", @vals). ")";
-
- my $sth = $self->SimpleQuery($QueryString, @bind);
- return ($sth);
- }
-# }}}
-
# {{{ sub Connect
=head2 Connect PARAMHASH: Driver, Database, Host, User, Password
@@ -358,6 +320,35 @@
# }}}
+# {{{ sub Insert
+=head2 Insert $TABLE_NAME @KEY_VALUE_PAIRS
+
+Takes a table name and a set of key-value pairs in an array. splits the key value pairs, constructs an INSERT statement and performs the insert. Returns the row_id of this row.
+
+=cut
+
+sub Insert {
+ my($self, $table, @pairs) = @_;
+ my(@cols, @vals, @bind);
+
+ #my %seen; #only the *first* value is used - allows drivers to specify default
+ while ( my $key = shift @pairs ) {
+ my $value = shift @pairs;
+ # next if $seen{$key}++;
+ push @cols, $key;
+ push @vals, '?';
+ push @bind, $value;
+ }
+
+ my $QueryString =
+ "INSERT INTO $table (". join(", ", @cols). ") VALUES ".
+ "(". join(", ", @vals). ")";
+
+ my $sth = $self->SimpleQuery($QueryString, @bind);
+ return ($sth);
+ }
+# }}}
+
# {{{ sub UpdateRecordValue
=head2 UpdateRecordValue
@@ -1061,6 +1052,10 @@
# {{{ POD
+=head1 AUTHOR
+
+Jesse Vincent, jesse at fsck.com
+
=head1 SEE ALSO
perl(1), L<DBIx::SearchBuilder>
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Informix.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Informix.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Informix.pm Sat Nov 13 20:25:06 2004
@@ -9,20 +9,17 @@
=head1 NAME
- DBIx::SearchBuilder::Handle::Informix -- an Informix specific Handle object
+ DBIx::SearchBuilder::Handle::Informix - An Informix specific Handle object
=head1 SYNOPSIS
=head1 DESCRIPTION
-=head1 AUTHOR
-
-Oliver Tappe, oliver at akso.de
+This module provides a subclass of DBIx::SearchBuilder::Handle that
+compensates for some of the idiosyncrasies of Informix.
-=head1 SEE ALSO
-
-perl(1), DBIx::SearchBuilder
+=head1 METHODS
=cut
@@ -30,12 +27,10 @@
=head2 Insert
-Takes a table name as the first argument and assumes that the rest of the arguments
-are an array of key-value pairs to be inserted.
-
+Takes a table name as the first argument and assumes that the rest of the arguments are an array of key-value pairs to be inserted.
If the insert succeeds, returns the id of the insert, otherwise, returns
-a Class::ReturnValue object with the error reploaded.
+a Class::ReturnValue object with the error reported.
=cut
@@ -56,7 +51,6 @@
# }}}
-
=head2 CaseSensitive
Returns 1, since Informix's searches are case sensitive by default
@@ -68,9 +62,13 @@
return(1);
}
-
# }}}
+=head2 BuildDSN
+
+Builder for Informix DSNs.
+
+=cut
sub BuildDSN {
my $self = shift;
@@ -145,3 +143,16 @@
# }}}
+1;
+
+__END__
+
+=head1 AUTHOR
+
+Oliver Tappe, oliver at akso.de
+
+=head1 SEE ALSO
+
+perl(1), DBIx::SearchBuilder
+
+=cut
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Handle/ODBC.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Handle/ODBC.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Handle/ODBC.pm Sat Nov 13 20:25:06 2004
@@ -7,11 +7,37 @@
use vars qw($VERSION @ISA $DBIHandle $DEBUG);
use strict;
+=head1 NAME
+
+ DBIx::SearchBuilder::Handle::ODBC - An ODBC specific Handle object
+
+=head1 SYNOPSIS
+
+
+=head1 DESCRIPTION
+
+This module provides a subclass of DBIx::SearchBuilder::Handle that
+compensates for some of the idiosyncrasies of ODBC.
+
+=head1 METHODS
+
+=cut
+
+=head2 CaseSensitive
+
+Returns a false value.
+
+=cut
+
sub CaseSensitive {
my $self = shift;
return (undef);
}
+=head2 BuildDSN
+
+=cut
+
sub BuildDSN {
my $self = shift;
my %args = (
@@ -29,6 +55,10 @@
$self->{'dsn'} = $dsn;
}
+=head2 ApplyLimits
+
+=cut
+
sub ApplyLimits {
my $self = shift;
my $statementref = shift;
@@ -40,6 +70,10 @@
$$statementref =~ s/SELECT\b/SELECT $limit_clause/;
}
+=head2 DistinctQuery
+
+=cut
+
sub DistinctQuery {
my $self = shift;
my $statementref = shift;
@@ -50,3 +84,16 @@
sub Encoding {
}
+1;
+
+__END__
+
+=head1 AUTHOR
+
+Autrijus Tang
+
+=head1 SEE ALSO
+
+DBIx::SearchBuilder, DBIx::SearchBuilder::Handle
+
+=cut
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Oracle.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Oracle.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Oracle.pm Sat Nov 13 20:25:06 2004
@@ -10,40 +10,26 @@
=head1 NAME
- DBIx::SearchBuilder::Handle::Oracle -- an oracle specific Handle object
+ DBIx::SearchBuilder::Handle::Oracle - An oracle specific Handle object
=head1 SYNOPSIS
=head1 DESCRIPTION
-=head1 AUTHOR
-
-Jesse Vincent, jesse at fsck.com
+This module provides a subclass of DBIx::SearchBuilder::Handle that
+compensates for some of the idiosyncrasies of Oracle.
-=head1 SEE ALSO
-
-perl(1), DBIx::SearchBuilder
+=head1 METHODS
=cut
-
-sub new {
- my $proto = shift;
- my $class = ref($proto) || $proto;
- my $self = {};
- bless ($self, $class);
- return ($self);
-}
-
-
# {{{ sub Connect
=head2 Connect PARAMHASH: Driver, Database, Host, User, Password
Takes a paramhash and connects to your DBI datasource.
-
=cut
sub Connect {
@@ -53,12 +39,11 @@
Database => undef,
User => undef,
Password => undef,
- SID => undef,
- Host => undef,
+ SID => undef,
+ Host => undef,
@_);
$self->SUPER::Connect(%args);
-
$self->dbh->{LongTruncOk}=1;
$self->dbh->{LongReadLen}=8000;
@@ -299,3 +284,15 @@
# }}}
1;
+
+__END__
+
+=head1 AUTHOR
+
+Jesse Vincent, jesse at fsck.com
+
+=head1 SEE ALSO
+
+perl(1), DBIx::SearchBuilder
+
+=cut
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Pg.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Pg.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Pg.pm Sat Nov 13 20:25:06 2004
@@ -10,7 +10,24 @@
use strict;
+=head1 NAME
+
+ DBIx::SearchBuilder::Handle::Pg - A Postgres specific Handle object
+
+=head1 SYNOPSIS
+
+
+=head1 DESCRIPTION
+
+This module provides a subclass of DBIx::SearchBuilder::Handle that
+compensates for some of the idiosyncrasies of Postgres.
+
+=head1 METHODS
+
+=cut
+
# {{{ sub Connect
+
=head2 Connect
Connect takes a hashref and passes it off to SUPER::Connect;
@@ -156,3 +173,12 @@
# }}}
1;
+
+__END__
+
+=head1 SEE ALSO
+
+DBIx::SearchBuilder, DBIx::SearchBuilder::Handle
+
+=cut
+
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Handle/SQLite.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Handle/SQLite.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Handle/SQLite.pm Sat Nov 13 20:25:06 2004
@@ -8,20 +8,17 @@
=head1 NAME
- DBIx::SearchBuilder::Handle::SQLite -- a mysql specific Handle object
+ DBIx::SearchBuilder::Handle::SQLite -- A SQLite specific Handle object
=head1 SYNOPSIS
=head1 DESCRIPTION
-=head1 AUTHOR
-
-Jesse Vincent, jesse at fsck.com
+This module provides a subclass of DBIx::SearchBuilder::Handle that
+compensates for some of the idiosyncrasies of SQLite.
-=head1 SEE ALSO
-
-perl(1), DBIx::SearchBuilder
+=head1 METHODS
=cut
@@ -32,9 +29,8 @@
Takes a table name as the first argument and assumes that the rest of the arguments
are an array of key-value pairs to be inserted.
-
If the insert succeeds, returns the id of the insert, otherwise, returns
-a Class::ReturnValue object with the error reploaded.
+a Class::ReturnValue object with the error reported.
=cut
@@ -61,7 +57,7 @@
=head2 CaseSensitive
-Returns undef, since mysql's searches are not case sensitive by default
+Returns undef, since SQLite's searches are not case sensitive by default
=cut
@@ -96,14 +92,17 @@
# }}}
+=head2 _BuildJoins
+
+Adjusts syntax of join queries for SQLite.
+
+=cut
#SQLite can't handle
# SELECT DISTINCT main.* FROM (Groups main LEFT JOIN Principals Principals_2 ON ( main.id = Principals_2.id)) , GroupMembers GroupMembers_1 WHERE ((GroupMembers_1.MemberId = '70')) AND ((Principals_2.Disabled = '0')) AND ((main.Domain = 'UserDefined')) AND ((main.id = GroupMembers_1.GroupId))
# ORDER BY main.Name ASC
# It needs
-#SELECT DISTINCT main.* FROM Groups main LEFT JOIN Principals Principals_2 ON ( main.id = Principals_2.id) , GroupMembers GroupMembers_1 WHERE ((GroupMembers_1.MemberId = '70')) AND ((Principals_2.Disabled = '0')) AND ((main.Domain = 'UserDefined')) AND ((main.id = GroupMembers_1.GroupId)) ORDER BY main.Name ASC
-
-
+# SELECT DISTINCT main.* FROM Groups main LEFT JOIN Principals Principals_2 ON ( main.id = Principals_2.id) , GroupMembers GroupMembers_1 WHERE ((GroupMembers_1.MemberId = '70')) AND ((Principals_2.Disabled = '0')) AND ((main.Domain = 'UserDefined')) AND ((main.id = GroupMembers_1.GroupId)) ORDER BY main.Name ASC
sub _BuildJoins {
my $self = shift;
@@ -147,5 +146,16 @@
}
-
1;
+
+__END__
+
+=head1 AUTHOR
+
+Jesse Vincent, jesse at fsck.com
+
+=head1 SEE ALSO
+
+perl(1), DBIx::SearchBuilder
+
+=cut
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Sybase.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Sybase.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Handle/Sybase.pm Sat Nov 13 20:25:06 2004
@@ -16,13 +16,10 @@
=head1 DESCRIPTION
-=head1 AUTHOR
-
-Jesse Vincent, jesse at fsck.com
-
-=head1 SEE ALSO
+This module provides a subclass of DBIx::SearchBuilder::Handle that
+compensates for some of the idiosyncrasies of Sybase.
-perl(1), DBIx::SearchBuilder
+=head1 METHODS
=cut
@@ -33,9 +30,8 @@
Takes a table name as the first argument and assumes that the rest of the arguments
are an array of key-value pairs to be inserted.
-
If the insert succeeds, returns the id of the insert, otherwise, returns
-a Class::ReturnValue object with the error reploaded.
+a Class::ReturnValue object with the error reported.
=cut
@@ -140,3 +136,16 @@
# }}}
+1;
+
+__END__
+
+=head1 AUTHOR
+
+Jesse Vincent, jesse at fsck.com
+
+=head1 SEE ALSO
+
+DBIx::SearchBuilder, DBIx::SearchBuilder::Handle
+
+=cut
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Handle/mysql.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Handle/mysql.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Handle/mysql.pm Sat Nov 13 20:25:06 2004
@@ -9,20 +9,17 @@
=head1 NAME
- DBIx::SearchBuilder::Handle::mysql -- a mysql specific Handle object
+ DBIx::SearchBuilder::Handle::mysql - A mysql specific Handle object
=head1 SYNOPSIS
=head1 DESCRIPTION
-=head1 AUTHOR
-
-Jesse Vincent, jesse at fsck.com
-
-=head1 SEE ALSO
+This module provides a subclass of DBIx::SearchBuilder::Handle that
+compensates for some of the idiosyncrasies of MySQL.
-perl(1), DBIx::SearchBuilder
+=head1 METHODS
=cut
@@ -30,12 +27,10 @@
=head2 Insert
-Takes a table name as the first argument and assumes that the rest of the arguments
-are an array of key-value pairs to be inserted.
-
+Takes a table name as the first argument and assumes that the rest of the arguments are an array of key-value pairs to be inserted.
If the insert succeeds, returns the id of the insert, otherwise, returns
-a Class::ReturnValue object with the error reploaded.
+a Class::ReturnValue object with the error reported.
=cut
@@ -48,12 +43,13 @@
}
$self->{'id'}=$self->dbh->{'mysql_insertid'};
- # Yay. we get to work around mysql_insertid being null some of the time :/
+ # Yay. we get to work around mysql_insertid being null some of the time :/
unless ($self->{'id'}) {
$self->{'id'} = $self->FetchResult('SELECT LAST_INSERT_ID()');
}
warn "$self no row id returned on row creation" unless ($self->{'id'});
+
return( $self->{'id'}); #Add Succeded. return the id
}
@@ -62,7 +58,7 @@
=head2 DatabaseVersion
-return the mysql version, trimming off any -foo identifier
+Returns the mysql version, trimming off any -foo identifier
=cut
@@ -70,9 +66,8 @@
my $self = shift;
my $v = $self->SUPER::DatabaseVersion();
- $v =~ s/\-(.*)$//;
+ $v =~ s/\-.*$//;
return ($v);
-
}
=head2 CaseSensitive
@@ -86,7 +81,19 @@
return(undef);
}
-
# }}}
+1;
+
+__END__
+
+=head1 AUTHOR
+
+Jesse Vincent, jesse at fsck.com
+
+=head1 SEE ALSO
+
+DBIx::SearchBuilder, DBIx::SearchBuilder::Handle
+
+=cut
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Handle/mysqlPP.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Handle/mysqlPP.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Handle/mysqlPP.pm Sat Nov 13 20:25:06 2004
@@ -1,17 +1,31 @@
+package DBIx::SearchBuilder::Handle::mysqlPP;
+use DBIx::SearchBuilder::Handle::mysql;
+ at ISA = qw(DBIx::SearchBuilder::Handle::mysql);
+
+use vars qw($VERSION @ISA $DBIHandle $DEBUG);
+use strict;
+
+1;
+
+__END__
=head1 NAME
-DBIx::SearchBuilder::Handle::mysqlPP
+DBIx::SearchBuilder::Handle::mysqlPP - A mysql specific Handle object
=head1 DESCRIPTION
-A handler for the "pure perl" mysql database handler
+A Handle subclass for the "pure perl" mysql database driver.
+
+This is currently identical to the DBIx::SearchBuilder::Handle::mysql class.
+
+=head1 AUTHOR
+
+
+
+=head1 SEE ALSO
+
+DBIx::SearchBuilder::Handle::mysql
=cut
-package DBIx::SearchBuilder::Handle::mysqlPP;
-use DBIx::SearchBuilder::Handle::mysql;
- at ISA = qw(DBIx::SearchBuilder::Handle::mysql);
-
-use vars qw($VERSION @ISA $DBIHandle $DEBUG);
-use strict;
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Record.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Record.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Record.pm Sat Nov 13 20:25:06 2004
@@ -12,84 +12,81 @@
=head1 NAME
-DBIx::SearchBuilder::Record - Perl extension for subclassing, so you can deal with a Record
+DBIx::SearchBuilder::Record - Superclass for records loaded by SearchBuilder
=head1 SYNOPSIS
-module MyRecord;
-use base qw/DBIx::SearchBuilder::Record/;
-
-sub _Init {
- my $self = shift;
- my $DBIxHandle =
- shift; # A DBIx::SearchBuilder::Handle::foo object for your database
-
- $self->_Handle($DBIxHandle);
- $self->Table("Users");
-}
-
-# Tell Record what the primary keys are
-sub _PrimaryKeys {
- my $self = shift;
- return ['id'];
-}
-
-#Preferred and most efficient way to specify fields attributes in a derived
-#class, used by the autoloader to construct Attrib and SetAttrib methods.
-
-# read: calling $Object->Foo will return the value of this record's Foo column # write: calling $Object->SetFoo with a single value will set Foo's value in
-# both the loaded object and the database
-
-sub _ClassAccessible {
- {
- Tofu => { 'read' => 1, 'write' => 1 },
- Maz => { 'auto' => 1, },
- Roo => { 'read' => 1, 'auto' => 1, 'public' => 1, },
- };
-}
-
-# A subroutine to check a user's password without ever returning the current password
-#For security purposes, we didn't expose the Password method above
-
-sub IsPassword {
- my $self = shift;
- my $try = shift;
-
- # note two __s in __Value. Subclasses may muck with _Value, but they should
- # never touch __Value
-
- if ( $try eq $self->__Value('Password') ) {
- return (1);
- }
- else {
- return (undef);
- }
-
-}
-
-# Override DBIx::SearchBuilder::Create to do some checking on create
-sub Create {
- my $self = shift;
- my %fields = (
- UserId => undef,
- Password => 'default', #Set a default password
- @_
- );
-
- #Make sure a userid is specified
- unless ( $fields{'UserId'} ) {
- die "No userid specified.";
- }
+ package MyRecord;
+ use base qw/DBIx::SearchBuilder::Record/;
+
+ sub _Init {
+ my $self = shift;
+ my $DBIxHandle =
+ shift; # A DBIx::SearchBuilder::Handle::foo object for your database
+
+ $self->_Handle($DBIxHandle);
+ $self->Table("Users");
+ }
+
+ # Tell Record what the primary keys are
+ sub _PrimaryKeys {
+ return ['id'];
+ }
+
+ # Preferred and most efficient way to specify fields attributes in a derived
+ # class, used by the autoloader to construct Attrib and SetAttrib methods.
- #Get DBIx::SearchBuilder::Record->Create to do the real work
- return (
- $self->SUPER::Create(
- UserId => $fields{'UserId'},
- Password => $fields{'Password'},
- Created => time
- )
- );
-}
+ # read: calling $Object->Foo will return the value of this record's Foo column
+ # write: calling $Object->SetFoo with a single value will set Foo's value in
+ # both the loaded object and the database
+ sub _ClassAccessible {
+ {
+ Tofu => { 'read' => 1, 'write' => 1 },
+ Maz => { 'auto' => 1, },
+ Roo => { 'read' => 1, 'auto' => 1, 'public' => 1, },
+ };
+ }
+
+ # A subroutine to check a user's password without returning the current value
+ # For security purposes, we didn't expose the Password method above
+ sub IsPassword {
+ my $self = shift;
+ my $try = shift;
+
+ # note two __s in __Value. Subclasses may muck with _Value, but
+ # they should never touch __Value
+
+ if ( $try eq $self->__Value('Password') ) {
+ return (1);
+ }
+ else {
+ return (undef);
+ }
+ }
+
+ # Override DBIx::SearchBuilder::Create to do some checking on create
+ sub Create {
+ my $self = shift;
+ my %fields = (
+ UserId => undef,
+ Password => 'default', #Set a default password
+ @_
+ );
+
+ # Make sure a userid is specified
+ unless ( $fields{'UserId'} ) {
+ die "No userid specified.";
+ }
+
+ # Get DBIx::SearchBuilder::Record->Create to do the real work
+ return (
+ $self->SUPER::Create(
+ UserId => $fields{'UserId'},
+ Password => $fields{'Password'},
+ Created => time
+ )
+ );
+ }
=head1 DESCRIPTION
@@ -98,7 +95,7 @@
=head2 What is it trying to do.
-DBIx::SB::Record abstracts the agony of writing the common and generally
+DBIx::SearchBuilder::Record abstracts the agony of writing the common and generally
simple SQL statements needed to serialize and De-serialize an object to the
database. In a traditional system, you would define various methods on
your object 'create', 'find', 'modify', and 'delete' being the most common.
@@ -127,105 +124,129 @@
have guessed the '_' suggests that these are private methods, they are.
They will get called by your record objects constructor.
- o. '_Init'
- Defines what table we are talking about, and set a variable to store
- the database handle.
-
- o. '_ClassAccessible
- Defines what operations may be performed on various data selected
- from the database. For example you can define fields to be mutable,
- or immutable, there are a few other options but I don't understand
- what they do at this time.
-
-And really, thats it. So lets have some sample code, but first the example
-code makes the following assumptions:
-
- The database is 'postgres',
- The host is 'reason',
- The login name is 'mhat',
- The database is called 'example',
- The table is called 'simple',
- The table looks like so:
+=over 4
+
+=item '_Init'
+
+Defines what table we are talking about, and set a variable to store
+the database handle.
+
+=item '_ClassAccessible
+
+Defines what operations may be performed on various data selected
+from the database. For example you can define fields to be mutable,
+or immutable, there are a few other options but I don't understand
+what they do at this time.
+
+=back
+
+And really, thats it. So lets have some sample code.
+
+=head2 An Annotated Example
+
+The example code below makes the following assumptions:
+
+=over 4
+
+=item *
+
+The database is 'postgres',
+
+=item *
+
+The host is 'reason',
+
+=item *
+
+The login name is 'mhat',
+
+=item *
+
+The database is called 'example',
+
+=item *
+
+The table is called 'simple',
+
+=item *
+
+The table looks like so:
id integer not NULL, primary_key(id),
foo varchar(10),
bar varchar(10)
+=back
-[file:///example/Simple.pm]
+First, let's define our record class in a new module named "Simple.pm".
-000: package Simple;
-001: use DBIx::SearchBuilder::Record;
-002: @ISA = (DBIx::SearchBuilder::Record);
+ 000: package Simple;
+ 001: use DBIx::SearchBuilder::Record;
+ 002: @ISA = (DBIx::SearchBuilder::Record);
This should be pretty obvious, name the package, import ::Record and then
define ourself as a subclass of ::Record.
-
-003:
-004: sub _Init {
-005: my $this = shift;
-006: my $handle = shift;
-007:
-008: $this->_Handle($handle);
-009: $this->Table("Simple");
-010:
-011: return ($this);
-012: }
+ 003:
+ 004: sub _Init {
+ 005: my $this = shift;
+ 006: my $handle = shift;
+ 007:
+ 008: $this->_Handle($handle);
+ 009: $this->Table("Simple");
+ 010:
+ 011: return ($this);
+ 012: }
Here we set our handle and table name, while its not obvious so far, we'll
see later that $handle (line: 006) gets passed via ::Record::new when a
new instance is created. Thats actually an important concept, the DB handle
is not bound to a single object but rather, its shared across objects.
-
-013:
-014: sub _ClassAccessible {
-015: {
-016: Foo => { 'read' => 1 },
-017: Bar => { 'read' => 1, 'write' => 1 },
-018: Id => { 'read' => 1 }
-019: };
-020: }
+ 013:
+ 014: sub _ClassAccessible {
+ 015: {
+ 016: Foo => { 'read' => 1 },
+ 017: Bar => { 'read' => 1, 'write' => 1 },
+ 018: Id => { 'read' => 1 }
+ 019: };
+ 020: }
What's happening might be obvious, but just in case this method is going to
return a reference to a hash. That hash is where our columns are defined,
as well as what type of operations are acceptable.
+ 021:
+ 022: 1;
-021:
-022: 1;
-
-Its perl, duh.
-
-
+Like all perl modules, this needs to end with a true value.
Now, on to the code that will actually *do* something with this object.
+This code would be placed in your Perl script.
-[file://examples/ex.pl]
-000: use DBIx::SearchBuilder::Handle;
-001: use Simple;
+ 000: use DBIx::SearchBuilder::Handle;
+ 001: use Simple;
Use two packages, the first is where I get the DB handle from, the latter
is the object I just created.
-002:
-003: my $handle = DBIx::SearchBuilder::Handle->new();
-004: $handle->Connect( 'Driver' => 'Pg',
-005: 'Database' => 'test',
-006: 'Host' => 'reason',
-007: 'User' => 'mhat',
-008: 'Password' => '');
+ 002:
+ 003: my $handle = DBIx::SearchBuilder::Handle->new();
+ 004: $handle->Connect( 'Driver' => 'Pg',
+ 005: 'Database' => 'test',
+ 006: 'Host' => 'reason',
+ 007: 'User' => 'mhat',
+ 008: 'Password' => '');
-Creates a new DBIx::SB::Handle, and then connects to the database using
+Creates a new DBIx::SearchBuilder::Handle, and then connects to the database using
that handle. Pretty straight forward, the password '' is what I use
when there is no password. I could probably leave it blank, but I find
it to be more clear to define it.
-009:
-010: my $s = new Simple($handle);
-011:
-012: $s->LoadById(1);
+ 009:
+ 010: my $s = Simple->new($handle);
+ 011:
+ 012: $s->LoadById(1);
LoadById is one of four 'LoadBy' methods, as the name suggests it searches
for an row in the database that has id='0'. ::SearchBuilder has, what I
@@ -235,19 +256,25 @@
In addition to LoadById, we also have:
- o. LoadByCol
- Takes two arguments, a column name and a value. Again, it will do
- undefined things if you use non-unique things.
-
- o. LoadByCols
- Takes a hash of columns=>values and returns the *first* to match.
- First is probably lossy across databases vendors.
-
- o. LoadFromHash
- Populates this record with data from a DBIx::SearchBuilder. I'm
- currently assuming that DBIx::SearchBuilder is what we use in
- cases where we expect > 1 record. More on this later.
+=over 4
+
+=item LoadByCol
+
+Takes two arguments, a column name and a value. Again, it will do
+undefined things if you use non-unique things.
+
+=item LoadByCols
+
+Takes a hash of columns=>values and returns the *first* to match.
+First is probably lossy across databases vendors.
+
+=item LoadFromHash
+Populates this record with data from a DBIx::SearchBuilder. I'm
+currently assuming that DBIx::SearchBuilder is what we use in
+cases where we expect > 1 record. More on this later.
+
+=back
Now that we have a populated object, we should do something with it! ::Record
automagically generates accessos and mutators for us, so all we need to do
@@ -255,62 +282,58 @@
Set<Field>($). On to the example, just appending this to the code from
the last example.
-013:
-014: print "ID : ", $s->Id(), "\n";
-015: print "Foo : ", $s->Foo(), "\n";
-016: print "Bar : ", $s->Bar(), "\n";
+ 013:
+ 014: print "ID : ", $s->Id(), "\n";
+ 015: print "Foo : ", $s->Foo(), "\n";
+ 016: print "Bar : ", $s->Bar(), "\n";
Thats all you have to to get the data, now to change the data!
-
-017:
-018: $s->SetBar('NewBar');
+ 017:
+ 018: $s->SetBar('NewBar');
Pretty simple! Thats really all there is to it. Set<Field>($) returns
a boolean and a string describing the problem. Lets look at an example of
what will happen if we try to set a 'Id' which we previously defined as
read only.
-019: my ($res, $str) = $s->SetId('2');
-020: if (! $res) {
-021: ## Print the error!
-022: print "$str\n";
-023: }
+ 019: my ($res, $str) = $s->SetId('2');
+ 020: if (! $res) {
+ 021: ## Print the error!
+ 022: print "$str\n";
+ 023: }
The output will be:
+
>> Immutable field
Currently Set<Field> updates the data in the database as soon as you call
it. In the future I hope to extend ::Record to better support transactional
operations, such that updates will only happen when "you" say so.
-
Finally, adding a removing records from the database. ::Record provides a
Create method which simply takes a hash of key=>value pairs. The keys
exactly map to database fields.
-
-023: ## Get a new record object.
-024: $s1 = new Simple($handle);
-025: $s1->Create('Id' => 4,
-026: 'Foo' => 'Foooooo',
-027: 'Bar' => 'Barrrrr');
+ 023: ## Get a new record object.
+ 024: $s1 = Simple->new($handle);
+ 025: $s1->Create('Id' => 4,
+ 026: 'Foo' => 'Foooooo',
+ 027: 'Bar' => 'Barrrrr');
Poof! A new row in the database has been created! Now lets delete the
object!
-028:
-029: $s1 = undef;
-030: $s1 = new Simple($handle);
-031: $s1->LoadById(4);
-032: $s1->Delete();
+ 028:
+ 029: $s1 = undef;
+ 030: $s1 = Simple->new($handle);
+ 031: $s1->LoadById(4);
+ 032: $s1->Delete();
And its gone.
-
-
-For simple use, thats more or less all there is to it. The next part of
-this HowTo will discuss using container classes, overloading, and what
+For simple use, thats more or less all there is to it. In the future, I hope to exapand
+this HowTo to discuss using container classes, overloading, and what
ever else I think of.
@@ -322,7 +345,7 @@
# }}}
-=head2 sub new
+=head2 new
Instantiate a new record object.
@@ -355,12 +378,14 @@
*Id = \&id;
sub id {
- $_[0]->{'values'}->{'id'};
+ my $pkey = $_[0]->_PrimaryKey();
+ $_[0]->{'values'}->{$pkey};
}
# }}}
=head2 primary_keys
+
=head2 PrimaryKeys
Return a hash of the values of our primary keys for this function.
@@ -488,8 +513,7 @@
=head2 _PrimaryKeys
-Return our primary keys. (Subclasses should override this, but our default is "We have one primary key. It's called 'id');
-
+Return our primary keys. (Subclasses should override this, but our default is that we have one primary key, named 'id'.)
=cut
@@ -498,12 +522,23 @@
return ['id'];
}
+
+sub _PrimaryKey {
+ my $self = shift;
+ my $pkeys = $self->_PrimaryKeys();
+ die "No primary key" unless ( ref($pkeys) eq 'ARRAY' and $pkeys->[0] );
+ die "Too many primary keys" unless ( scalar(@$pkeys) == 1 );
+ return $pkeys->[0];
+}
+
# {{{ sub _ClassAccessible
=head2 _ClassAccessible
Preferred and most efficient way to specify fields attributes in a derived
-class.
+class.
+
+Here's an example declaration:
sub _ClassAccessible {
{
@@ -525,7 +560,7 @@
$accessible{$col}->{lc($_)} = 1
foreach split(/[\/,]/, shift);
}
- return(\%accessible);
+ return(\%accessible);
}
# }}}
@@ -571,7 +606,7 @@
=head2 __Value
Takes a field name and returns that field's value. Subclasses should never
-overrid __Value.
+override __Value.
=cut
@@ -580,8 +615,9 @@
my $self = shift;
my $field = lc(shift);
- if (!$self->{'fetched'}{$field} and my $id = $self->{'values'}{'id'}) {
- my $QueryString = "SELECT $field FROM " . $self->Table . " WHERE id = ?";
+ if (!$self->{'fetched'}{$field} and my $id = $self->id() ) {
+ my $pkey = $self->_PrimaryKey();
+ my $QueryString = "SELECT $field FROM " . $self->Table . " WHERE $pkey = ?";
my $sth = $self->_Handle->SimpleQuery( $QueryString, $id );
my ($value) = eval { $sth->fetchrow_array() };
warn $@ if $@;
@@ -759,7 +795,7 @@
Truncate a value that's about to be set so that it will fit inside the database'
s idea of how big the column is.
-(Actually, it looks at searchbuilder's concept of the database, not directly into the db).
+(Actually, it looks at SearchBuilder's concept of the database, not directly into the db).
=cut
@@ -864,7 +900,7 @@
=head2 Load
-Takes a single argument, $id. Calls LoadByRow to retrieve the row whose primary key
+Takes a single argument, $id. Calls LoadById to retrieve the row whose primary key
is $id
=cut
@@ -873,9 +909,9 @@
*load = \&Load;
sub Load {
my $self = shift;
- my ($package, $filename, $line) = caller;
+ # my ($package, $filename, $line) = caller;
return $self->LoadById(@_);
- }
+}
# }}}
# {{{ sub LoadByCol
@@ -896,8 +932,7 @@
my $val = shift;
return($self->LoadByCols($col => $val));
-
- }
+}
# }}}
@@ -911,10 +946,7 @@
The hash's keys are the columns to look at.
The hash's values are either: scalar values to look for
- OR has references which contain 'operator' and 'value'
-
-
-
+OR has references which contain 'operator' and 'value'
=cut
@@ -957,8 +989,7 @@
=head2 LoadById
-Loads a record by its primary key.
-TODO: BUG: Column name is currently hard coded to 'id'
+Loads a record by its primary key. Your record class must define a single primary key column.
=cut
@@ -968,7 +999,8 @@
my $id = shift;
$id = 0 if (!defined($id));
- return ($self->LoadByCols(id => $id));
+ my $pkey = $self->_PrimaryKey();
+ return ($self->LoadByCols($pkey => $id));
}
# }}}
@@ -978,11 +1010,12 @@
=head2 LoadByPrimaryKeys
+Like LoadById with basic support for compound primary keys.
+
=cut
*load_by_primary_keys = \&LoadByPrimaryKeys;
-
sub LoadByPrimaryKeys {
my ($self, $data) = @_;
@@ -1005,7 +1038,7 @@
=head2 LoadFromHash
- Takes a hashref, such as created by DBIx::SearchBuilder and populates this record's
+Takes a hashref, such as created by DBIx::SearchBuilder and populates this record's
loaded values hash.
=cut
@@ -1021,7 +1054,7 @@
}
$self->{'values'} = $hashref;
- return ($self->{'values'}{'id'});
+ return $self->id();
}
# }}}
@@ -1046,7 +1079,6 @@
#TODO this only gets the first row. we should check if there are more.
-
unless ($sth) {
return($sth);
}
@@ -1130,7 +1162,7 @@
=head2 Delete
- Delete this record from the database. On failure return a Class::ReturnValue with the error. On success, return 1;
+Delete this record from the database. On failure return a Class::ReturnValue with the error. On success, return 1;
=cut
@@ -1164,7 +1196,6 @@
} else {
return(1);
}
-
}
# }}}
@@ -1229,7 +1260,7 @@
=head1 SEE ALSO
-perl(1).
+L<DBIx::SearchBuilder>
=cut
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Record/Cachable.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Record/Cachable.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Record/Cachable.pm Sat Nov 13 20:25:06 2004
@@ -11,6 +11,29 @@
use strict;
+# {{{ Doc
+
+=head1 NAME
+
+DBIx::SearchBuilder::Record::Cachable - Records with caching behavior
+
+=head1 SYNOPSIS
+
+ package MyRecord;
+ use base qw/DBIx::SearchBuilder::Record::Cachable/;
+
+=head1 DESCRIPTION
+
+This module subclasses the main DBIx::SearchBuilder::Record package to add a caching layer.
+
+The public interface remains the same, except that records which have been loaded in the last few seconds may be reused by subsequent fetch or load methods without retrieving them from the database.
+
+=head1 METHODS
+
+=cut
+
+# }}}
+
my %_CACHES = ();
# Function: new
@@ -32,7 +55,6 @@
$_CACHES{$cache}->expire_after( $self->_CacheConfig->{'cache_for_sec'} );
}
-
=head2 FlushCache
This class method flushes the _global_ DBIx::SearchBuilder::Record::Cachable
@@ -285,10 +307,40 @@
}
+=head2 _CacheConfig
+
+You can override this method to change the duration of the caching from the default of 5 seconds.
+
+For example, to cache records for up to 30 seconds, add the following method to your class:
+
+ sub _CacheConfig {
+ { 'cache_for_sec' => 30 }
+ }
+
+=cut
+
sub _CacheConfig {
{
'cache_p' => 1,
'cache_for_sec' => 5,
};
}
+
1;
+
+__END__
+
+# {{{ POD
+
+=head1 AUTHOR
+
+Matt Knopp <mhat at netlag.com>
+
+=head1 SEE ALSO
+
+L<DBIx::SearchBuilder>, L<DBIx::SearchBuilder::Record>
+
+=cut
+
+# }}}
+
More information about the Rt-commit
mailing list