/ 
MorboDB-0.001002
River stage zero No dependents
/ MorboDB::Cursor

NAME

MorboDB::Cursor - A cursor/iterator for MorboDB query results

VERSION

version 0.001002

SYNOPSIS

my $cursor = $coll->find({ year => { '$gte' => 2000 } })->sort({ year => -1 });
while (my $object = $cursor->next) {
	...
}

my @objects = $cursor->all;

DESCRIPTION

This module provides an iterator/cursor for query operations performed on a MorboDB::Collection using the find()/query() methods.

ATTRIBUTES

started_iterating

A boolean value indicating whether the cursor has started looking for documents in the database. Initially false. When true, setting modifiers such as sort, fields, skip and limit is not possible without first calling reset().

immortal

Boolean value, means nothing in MorboDB.

tailable

Boolean value, not implemented in MorboDB.

partial

Boolean value, not implemented in MorboDB.

slave_okay

Boolean value, not implemented in MorboDB.

OBJECT METHODS

fields( \%fields )

Selects which fields are returned. The default is all fields. _id is always returned. Returns this cursor for chaining operations.

limit( $num )

Returns a maximum of $num results. Returns this cursor for chaining operations.

skip( $num )

Skips the first $num results. Returns this cursor for chaining operations.

sort( $order )

Adds a sort to the cursor. Argument is either a hash reference or a Tie::IxHash object. Returns this cursor for chaining operations.

snapshot()

Not implemented. Simply returns true here.

explain()

Not implemented. Simply returns true here.

reset()

Resets the cursor. After being reset, pre-query methods can be called on the cursor (sort, limit, etc.) and subsequent calls to next(), has_next(), or all() will re-query the database.

info()

Not implemented. Returns an empty hash-ref here.

count()

Returns the number of documents the query matched.

has_next()

Checks if there is another result to fetch.

next()

Returns the next object in the cursor. Returns undef if no more data is available.

all()

Returns an array of all objects in the result.

DIAGNOSTICS

This module throws the following exceptions:

cannot set fields/skip/limit/sort after querying

This error will be thrown when you're trying to modify the cursor after it has already started querying the database. You can tell if the cursor already started querying the database by taking a look at the started_iterating attribute. If you want to modify the cursor after iteration has started, you can used the reset() method, but the query will have to run again.

not a hash reference

This error is thrown by the fields() method when you're not providing it with a hash-reference of fields like so:

$cursor->fields({ name => 1, datetime => 1 });
sort() needs a Tie::IxHash object or a hash reference.

This error is thrown by the sort() method when you're not giving it a hash reference or Tie::IxHash object to sort according to, like so:

$cursor->sort(Tie::IxHash->new(name => 1, datetime => -1));

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-MorboDB@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MorboDB.

SEE ALSO

MongoDB::Cursor.

AUTHOR

Ido Perlmuter <ido@ido50.net>

LICENSE AND COPYRIGHT

Copyright (c) 2011, Ido Perlmuter ido@ido50.net.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either version 5.8.1 or any later version. See perlartistic and perlgpl.

The full text of the license can be found in the LICENSE file included with this module.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.