Data::ObjectDriver::ResultSet - Manage a DB query
# Get a resultset object for Object::Widget, which inherits from # Data::ObjectDriver::BaseObject my $result = Object::Widget->result($terms, $args); $result->add_term({color => 'blue'}); $result->add_limit(10); $result->add_offset(100); while (not $result->is_finished) { my $widget = $result->next; # Do stuff with $widget }
This object is returned by the 'result' method found in the Data::ObjectDriver::BaseObject class. This object manages a query and the resulting data. It allows additional search terms and arguments to be added and will not submit the query until a method that returns data is called. By passing this object around code in multiple places can alter the query easily until the data is needed.
Once a method returning data is called (next, count, etc) the query is submitted to the database and the returned data is managed by the ResultSet object like an iterator.
This method is actually defined in Data::ObjectDriver::BaseObject but it is the way a new ResultSet object is created.
Arguments:
Return value:
This method returns a Data::ObjectDriver::ResultSet object
Create a new result set object that takes existing data and operates only as an iterator, without any of the query management.
A Data::ObjectDriver::ResultSet object
Apply a constraint to the result. The format of the two arguments is the same as for Data::ObjectDriver::DBI::search
; Return value : Returns 1 if successful and 0 otherwise
; Notes : Do we fail if called after we've retrieved the result set? Ignore it? Requery?
; Example
$res->add_constraint({object_id => $id}, {limit => 100})
Apply a single search term to the result. Equivalent to:
$res->add_constraint($terms)
; Notes : Same question as for add_constraint
$res->add_term({object_id => $id})
Clear a single search term from the result.
; Notes : none
$res->clear_term(qw(limit offset))
Apply a limit to the result. Equivalent to:
$res->add_constraint({}, {limit => $limit})
; Notes :
$res->add_limit(100)
Clear any limit value in the result.
; Notes : None
$res->clear_limit
Add an offset for the results returned. Result set must also have a limit set at some point.
$res->add_offset(5_000)
Clear any offset value in the result.
$res->clear_offset
Add a sort order for the results returned.
; Notes : >none''
$res->add_order('ascend')
$res->clear_order
Return the current index into the result set.
; Return value : An integer giving the zero based index of the current element in the result set.
$idx = $res->index;
Retrieve the next item in the resultset
; Return value : The next object or undef if past the end of the result set
; Notes : Calling this method will force a DB query. All subsequent calls to curr will return this object
$obj = $res->next;
Retrieve the next item in the resultset WITHOUT advancing the cursor.
while ($bottle = $res->next){ if ($bottle->type eq 'Bud Light' && $res->peek_next->type eq 'Chimay'){ $bottle->pass; #don't spoil my palate }else{ $bottle->drink; } }
Retrieve the previous item in the result set
; Return value : The previous object or undef if before the beginning of the result set
; Notes : All subsequent calls to curr will return this object
$obj = $res->prev;
Retrieve the current item in the result set. This item is set by calls to next and prev
; Return value : The current object or undef if past the boundaries of the result set
$obj = $res->curr
Return a slice of the result set. This is logically equivalent to setting a limit and offset and then retrieving all the objects via -next>. If you call slice and then call next, you will get undef and additionally is_finished will be true.
; Return value : An array of objects
; Notes : Objects are index from 0 just like perl arrays.
my @objs = $res->slice(0, 20)
Get the count of the items in the result set.
; Return value : A scalar count of the number of items in the result set
; Notes : This will cause a count() query on the database if the result set hasn't been retrieved yet. If the result set has been retrieved it will just return the number of objects stored in the result set object.
$num = $res->count
Returns whether we've arrived at the end of the result set
; Return value : Returns 1 if we are finished iterating though the result set and 0 otherwise
while (not $res->is_finished) { my $obj = $res->next; # Stuff ... }
Set this and you'll see $Data::ObjectDriver::DEBUG output when I go to get the results.
Move back to the start of the iterator for this instance of results of a query.
Returns the first object in the result set.
; Return value : The first object in the result set
; Notes : Resets the current cursor so that calls to curr return this value.
$obj = $res->first
Returns the last object in the result set.
; Return value : The last object in the result set
$obj = $res->last
Returns 1 if the cursor is on the last row of the result set, 0 if it is not.
; Return value : Returns 1 if the cursor is on the last row of the result set, 0 if it is not.
if ( $res->is_last ) { ## do some stuff }
To install Data::ObjectDriver, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::ObjectDriver
CPAN shell
perl -MCPAN -e shell install Data::ObjectDriver
For more information on module installation, please visit the detailed CPAN module installation guide.