view release on metacpan or  search on metacpan

lib/AnyEvent/CouchDB.pm  view on Meta::CPAN

many CouchDB requests asynchronously, and it was intended to be used within
a L<Coro>+L<AnyEvent> environment.  However, it can also be used synchronously
if you want.

Its API is based on jquery.couch.js, but we've adapted the API slightly so that
it makes sense in an asynchronous Perl environment.

=head2 AnyEvent condvars

The main thing you have to remember is that all the data retrieval methods
return an AnyEvent condvar, C<$cv>.  If you want the actual data from the
request, there are a few things you can do.

You may have noticed that many of the examples in the SYNOPSIS call C<recv>
on the condvar.  You're allowed to do this under 2 circumstances:

=over 4

=item Either you're in a main program,

Main programs are "allowed to call C<recv> blockingly", according to the
author of L<AnyEvent>.

=item or you're in a Coro + AnyEvent environment.

When you call C<recv> inside a coroutine, only that coroutine is blocked
while other coroutines remain active.  Thus, the program as a whole is
still responsive.

=back

If you're not using Coro, and you don't want your whole program to block,
what you should do is call C<cb> on the condvar, and give it a coderef to
execute when the results come back.  The coderef will be given a condvar
as a parameter, and it can call C<recv> on it to get the data.  The final
example in the SYNOPSIS gives a brief example of this.

Also note that C<recv> will throw an exception if the request fails, so be
prepared to catch exceptions where appropriate.

Please read the L<AnyEvent> documentation for more information on the proper
use of condvars.

=head2 The \%options Parameter

Many data retrieval methods will take an optional C<\%options> hashref.
Most of these options get turned into CGI query parameters.  The standard
CouchDB parameters are as follows:

=over 4

=item key=keyvalue

This lets you pick out one document with the specified key value.

=item startkey=keyvalue

This makes it so that lists start with a key value that is greater than or
equal to the specified key value.

=item startkey_docid=docid

This makes it so that lists start with a document with the specified docid.

=item endkey=keyvalue

This makes it so that lists end with a key value that is less than or
equal to the specified key value.

=item count=max_rows_to_return

This limits the number of results to the specified number or less.
If count is set to 0, you won't get any rows, but you I<will> get
the metadata for the request you made.

=item update=boolean

If you set C<update> to C<false>, CouchDB will skip doing any updating of a
view.  This will speed up the request, but you might not see all the latest
data.

=item descending=boolean

Views are sorted by their keys in ascending order.  However, if you set
C<descending> to C<true>, they'll come back in descending order.

=item skip=rows_to_skip

The skip option should only be used with small values, as skipping a large
range of documents this way is inefficient (it scans the index from the
startkey and then skips N elements, but still needs to read all the index
values to do that). For efficient paging use startkey and/or startkey_docid.

=back


You may also put subroutine references in the C<success> and C<error> keys of
this hashref, and they will be called upon success or failure of the request.



=head2 Documents Are Plain Hashrefs

Finally, note that the CouchDB documents you get back are plain hashrefs.  They
are not blessed into any kind of document class.


=head1 API

=head2 Convenience Functions

=head3 $couch = couch([ $uri ]);

This is a short-cut for:

  AnyEvent::CouchDB->new($uri)

and it is exported by default.  It will return a connection to a CouchDB server,
and if you don't pass it a URL, it'll assume L<http://localhost:5984/>.  Thus,
you can type:

  $couch = couch;

=head3 $db = couchdb($name_or_uri);

This function will construct an L<AnyEvent::CouchDB::Database> object for you.
If you only give it a name, it'll assume that the CouchDB server is at
L<http://localhost:5984/>.  You may also give it a full URL to a CouchDB
database to connect to.

This function is also exported by default.

=head2 Object Construction

=head3 $couch = AnyEvent::CouchDB->new([ $uri ])

This method will instantiate an object that represents a CouchDB server.
By default, it connects to L<http://localhost:5984/>, but you may explicitly
give it another URL if you want to connect to a CouchDB server on another
server or a non-default port.

=head3 $db = $couch->db($name)

This method takes a name and returns an L<AnyEvent::CouchDB::Database> object.
This is the object that you'll use to work with CouchDB documents.

=head2 Queries and Actions

=head3 $cv = $couch->all_dbs()

This method requests an arrayref that contains the names of all the databases
hosted on the current CouchDB server.  It returns an AnyEvent condvar that