[Rt-commit] r2937 - in DBIx-SearchBuilder/trunk: . SearchBuilder
glasser at bestpractical.com
glasser at bestpractical.com
Tue May 24 00:11:52 EDT 2005
Author: glasser
Date: Tue May 24 00:11:51 2005
New Revision: 2937
Modified:
DBIx-SearchBuilder/trunk/ (props changed)
DBIx-SearchBuilder/trunk/SearchBuilder.pm
DBIx-SearchBuilder/trunk/SearchBuilder/Unique.pm
Log:
r32875 at tin-foil: glasser | 2005-05-23 19:04:26 -0400
Doc fixes, and refactor into RecordCount
Modified: DBIx-SearchBuilder/trunk/SearchBuilder.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder.pm Tue May 24 00:11:51 2005
@@ -14,23 +14,50 @@
=head1 SYNOPSIS
use DBIx::SearchBuilder;
+
+ package My::Things;
+ use base qw/DBIx::SearchBuilder/;
+
+ sub _Init {
+ my $self = shift;
+ $self->Table('Things');
+ return $self->SUPER::_Init(@_);
+ }
+
+ sub NewItem {
+ my $self = shift;
+ # MyThing is a subclass of DBIx::SearchBuilder::Record
+ return(MyThing->new);
+ }
+
+ package main;
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" );
+ my $sb = My::Things->new( Handle => $handle );
$sb->Limit( FIELD => "column_1", VALUE => "matchstring" );
while ( my $record = $sb->Next ) {
- print $record->my_column_name();
+ print $record->my_column_name();
}
=head1 DESCRIPTION
This module provides an object-oriented mechanism for retrieving and updating data in a DBI-accesible database.
+In order to use this module, you should create a subclass of C<DBIx::SearchBuilder> and a
+subclass of C<DBIx::SearchBuilder::Record> for each table that you wish to access. (See
+the documentation of C<DBIx::SearchBuilder::Record> for more information on subclassing it.)
+
+Your C<DBIx::SearchBuilder> subclass must override C<NewItem>, and probably should override
+at least C<_Init> also; at the very least, C<_Init> should probably call C<_Handle> and C<_Table>
+to set the database handle (a C<DBIx::SearchBuilder::Handle> object) and table name for the class.
+You can try to override just about every other method here, as long as you think you know what you
+are doing.
+
=head1 METHOD NAMING
Each method has a lower case alias; '_' is used to separate words.
@@ -42,7 +69,20 @@
# {{{ sub new
-#instantiate a new object.
+=head2 new
+
+Creates a new SearchBuilder object and immediately calls C<_Init> with the same parameters
+that were passed to C<new>. If you haven't overridden C<_Init> in your subclass, this means
+that you should pass in a C<DBIx::SearchBuilder::Handle> (or one of its subclasses) like this:
+
+ my $sb = My::DBIx::SearchBuilder::Subclass->new( Handle => $handle );
+
+However, if your subclass overrides _Init you do not need to take a Handle argument, as long
+as your subclass returns an appropriate handle object from the C<_Handle> method. This is
+useful if you want all of your SearchBuilder objects to use a shared global handle and don't want
+to have to explicitly pass it in each time, for example.
+
+=cut
sub new {
my $proto = shift;
@@ -57,7 +97,13 @@
# {{{ sub _Init
-#Initialize the object
+=head2 _Init
+
+This method is called by C<new> with whatever arguments were passed to C<new>.
+By default, it takes a C<DBIx::SearchBuilder::Handle> object as a C<Handle>
+argument, although this is not necessary if your subclass overrides C<_Handle>.
+
+=cut
sub _Init {
my $self = shift;
@@ -75,8 +121,9 @@
=head2 CleanSlate
This completely erases all the data in the SearchBuilder object. It's
-useful if a subclass is doing funky stuff to keep track of
-a search
+useful if a subclass is doing funky stuff to keep track of a search and
+wants to reset the SearchBuilder data without losing its own data;
+it's probably cleaner to accomplish that in a different way, though.
=cut
@@ -127,6 +174,14 @@
# }}}
# {{{ sub _DoSearch
+
+=head2 _DoSearch
+
+This internal private method actually executes the search on the database;
+it is called automatically the first time that you actually need results
+(such as a call to C<Next>).
+
+=cut
sub _DoSearch {
my $self = shift;
@@ -137,11 +192,9 @@
delete $self->{'items'};
eval {
-
- # TODO: finer-grained eval and cheking.
- my $records = $self->_Handle->SimpleQuery($QueryString);
- my $counter;
- $self->{'rows'} = 0;
+ # TODO: finer-grained eval and checking.
+ my $records = $self->_Handle->SimpleQuery($QueryString);
+
while ( my $row = $records->fetchrow_hashref() ) {
my $item = $self->NewItem();
$item->LoadFromHash($row);
@@ -151,27 +204,47 @@
$self->{'must_redo_search'} = 0;
};
- return ( $self->{'rows'});
+ return $self->_RecordCount;
}
# }}}
=head2 AddRecord RECORD
-Adds a record object to this collection
+Adds a record object to this collection.
=cut
sub AddRecord {
my $self = shift;
my $record = shift;
- push @{$self->{'items'}}, $record;
- $self->{'rows'}++;
+ push @{$self->{'items'}}, $record;
+}
+
+=head2 _RecordCount
+
+This private internal method returns the number of Record objects saved
+as a result of the last query.
+
+=cut
+
+sub _RecordCount {
+ my $self = shift;
+ return 0 unless defined $self->{'items'};
+ return scalar @{ $self->{'items'} };
}
# {{{ sub _DoCount
+=head2 _DoCount
+
+This internal private method actually executes a counting operation on the database;
+it is used by C<Count> and C<CountAll>.
+
+=cut
+
+
sub _DoCount {
my $self = shift;
my $all = shift || 0;
@@ -194,8 +267,8 @@
=head2 _ApplyLimits STATEMENTREF
This routine takes a reference to a scalar containing an SQL statement.
-It massages the statement to limit the returned rows to $self->RowsPerPage
-starting with $self->FirstRow
+It massages the statement to limit the returned rows only $self->RowsPerPage,
+starting with $self->FirstRow.
=cut
@@ -208,7 +281,7 @@
$$statementref =~ s/main\.\*/join(', ', @{$self->{columns}})/eg
if $self->{columns} and @{$self->{columns}};
if (my $groupby = $self->_GroupClause) {
- $$statementref =~ s/(LIMIT \d+)?$/$groupby $1/;
+ $$statementref =~ s/(LIMIT \d+)?$/$groupby $1/;
}
}
@@ -412,7 +485,7 @@
$self->_DoSearch() if ( $self->{'must_redo_search'} != 0 );
- if ( $self->{'itemscount'} < $self->{'rows'} ) { #return the next item
+ if ( $self->{'itemscount'} < $self->_RecordCount ) { #return the next item
my $item = ( $self->{'items'}[ $self->{'itemscount'} ] );
$self->{'itemscount'}++;
return ($item);
@@ -1372,7 +1445,7 @@
# If we have loaded everything from the DB we have an
# accurate count already.
else {
- return ( $self->{'rows'} );
+ return $self->_RecordCount;
}
}
@@ -1427,7 +1500,7 @@
# If we have loaded everything from the DB we have an
# accurate count already.
else {
- return ( $self->{'rows'} );
+ return $self->_RecordCount;
}
}
@@ -1601,7 +1674,7 @@
=head2 Table [TABLE]
-If called with an arguemnt, sets this collection's table.
+If called with an argument, sets this collection's table.
Always returns this collection's table.
Modified: DBIx-SearchBuilder/trunk/SearchBuilder/Unique.pm
==============================================================================
--- DBIx-SearchBuilder/trunk/SearchBuilder/Unique.pm (original)
+++ DBIx-SearchBuilder/trunk/SearchBuilder/Unique.pm Tue May 24 00:11:51 2005
@@ -17,7 +17,6 @@
$self->{"dbix_sb_unique_cache"} = {} unless (@{$self->{'items'}}[0]);
return if $self->{"dbix_sb_unique_cache"}->{$record->id}++;
push @{$self->{'items'}}, $record;
- $self->{'rows'}++;
}
1;
More information about the Rt-commit
mailing list