# PODNAME: Yancy::Backend

#pod =head1 SYNOPSIS
#pod
#pod     my $be = Yancy::Backend->new( $url );
#pod
#pod     $result = $be->list( $collection, $where, $options );
#pod     say "Total: " . $result->{total};
#pod     say "Name: " . $_->{name} for @{ $result->{rows} };
#pod
#pod     $item = $be->get( $collection, $id );
#pod     $be->set( $collection, $id, $item );
#pod     $be->delete( $collection, $id );
#pod     $item = $be->create( $collection, $id, $item );
#pod
#pod =head1 DESCRIPTION
#pod
#pod A C<Yancy::Backend> handles talking to the database. Different Yancy
#pod backends will support different databases. To use a backend, see
#pod L</SUPPORTED BACKENDS>. To make your own backend, see L</METHODS> for
#pod the list of methods you must implement, their arguments, and their
#pod return values.
#pod
#pod =head2 Terminology
#pod
#pod Yancy backends work with collections, which are made up of items.
#pod A collection is a set of items, like a database table. An item is
#pod a single element of a collection, and must be a hashref.
#pod
#pod =head1 SUPPORTED BACKENDS
#pod
#pod =over
#pod
#pod =item * L<Yancy::Backend::Pg> - Postgres backend
#pod
#pod =item * L<Yancy::Backend::Mysql> - MySQL backend
#pod
#pod =item * L<Yancy::Backend::Dbic> - L<DBIx::Class> backend
#pod
#pod =back
#pod
#pod =head1 METHODS
#pod
#pod =head2 new
#pod
#pod     my $url = 'test://custom_string';
#pod     my $be = Yancy::Backend::Test->new( $url, $collections );
#pod
#pod Create a new backend object. C<$url> is a string that begins with the
#pod backend name followed by a colon and two slashes. Everything else in the
#pod URL is for the backend to use to describe how to connect to the
#pod underlying database and any options for the backend object itself.
#pod
#pod C<$collections> is a hash reference of collection configuration from the
#pod Yancy configuration. Important configuration for the backend to support:
#pod
#pod =over
#pod
#pod =item x-id-field
#pod
#pod The name of the ID field for the collection. Defaults to C<id>.
#pod
#pod =back
#pod
#pod The backend name will be run through C<ucfirst> before being looked up
#pod in C<Yancy::Backend::>. For example, C<mysql://...> will use the
#pod L<Yancy::Backend::Mysql> module.
#pod
#pod =head2 list
#pod
#pod     my $result = $be->list( $collection, $where, $opt );
#pod     # { total => ..., rows => [ ... ] }
#pod
#pod Fetch a list of items from a collection. C<$collection> is the
#pod collection name. C<$where> is a L<SQL::Abstract where
#pod structure|SQL::Abstract/WHERE CLAUSES>.
#pod
#pod C<$opt> is a hash reference with the following keys:
#pod
#pod =over
#pod
#pod =item * limit - The number of rows to return
#pod
#pod =item * offset - The number of rows to skip
#pod
#pod =item * order_by - A L<SQL::Abstract order by clause|SQL::Abstract/ORDER BY CLAUSES>
#pod
#pod =cut

Returns a hashref with two keys:

__END__

=pod

=head1 NAME

Yancy::Backend

=head1 VERSION

version 0.005

=head1 SYNOPSIS

    my $be = Yancy::Backend->new( $url );

    $result = $be->list( $collection, $where, $options );
    say "Total: " . $result->{total};
    say "Name: " . $_->{name} for @{ $result->{rows} };

    $item = $be->get( $collection, $id );
    $be->set( $collection, $id, $item );
    $be->delete( $collection, $id );
    $item = $be->create( $collection, $id, $item );

=head1 DESCRIPTION

A C<Yancy::Backend> handles talking to the database. Different Yancy
backends will support different databases. To use a backend, see
L</SUPPORTED BACKENDS>. To make your own backend, see L</METHODS> for
the list of methods you must implement, their arguments, and their
return values.

=head2 Terminology

Yancy backends work with collections, which are made up of items.
A collection is a set of items, like a database table. An item is
a single element of a collection, and must be a hashref.

=head1 SUPPORTED BACKENDS

=over

=item * L<Yancy::Backend::Pg> - Postgres backend

=item * L<Yancy::Backend::Mysql> - MySQL backend

=item * L<Yancy::Backend::Dbic> - L<DBIx::Class> backend

=back

=head1 METHODS

=head2 new

    my $url = 'test://custom_string';
    my $be = Yancy::Backend::Test->new( $url, $collections );

Create a new backend object. C<$url> is a string that begins with the
backend name followed by a colon and two slashes. Everything else in the
URL is for the backend to use to describe how to connect to the
underlying database and any options for the backend object itself.

C<$collections> is a hash reference of collection configuration from the
Yancy configuration. Important configuration for the backend to support:

=over

=item x-id-field

The name of the ID field for the collection. Defaults to C<id>.

=back

The backend name will be run through C<ucfirst> before being looked up
in C<Yancy::Backend::>. For example, C<mysql://...> will use the
L<Yancy::Backend::Mysql> module.

=head2 list

    my $result = $be->list( $collection, $where, $opt );
    # { total => ..., rows => [ ... ] }

Fetch a list of items from a collection. C<$collection> is the
collection name. C<$where> is a L<SQL::Abstract where
structure|SQL::Abstract/WHERE CLAUSES>.

C<$opt> is a hash reference with the following keys:

=over

=item * limit - The number of rows to return

=item * offset - The number of rows to skip

=item * order_by - A L<SQL::Abstract order by clause|SQL::Abstract/ORDER BY CLAUSES>

=over

=item rows

An array reference of hash references of item data

=item total

The total count of rows that would be returned without C<limit> or
C<offset>.

=back

=head2 get

    my $item = $be->get( $collection, $id );

Get a single item. C<$collection> is the collection name. C<$id> is the
ID of the item to get. Returns a hashref of item data.

=head2 set

    $be->set( $collection, $id, $item );

Update an item. C<$collection> is the collection name. C<$id> is the
ID of the item to update. C<$item> is the item's data to set. There is
no return value.

=head2 create

    $item = $be->create( $collection, $item );

Create a new item. C<$collection> is the collection name.  C<$item> is
the item's data. Returns the item's data after being saved in the
database (so, including any defaults or autogenerated data).

=head2 delete

    $be->delete( $collection, $id );

Delete an item. C<$collection> is the collection name. C<$id> is the
ID of the item to delete.

=head1 AUTHOR

Doug Bell <preaction@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Doug Bell.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut
