File Coverage

lib/DBIx/Simple/OO.pm

Criterion	Covered	Total	%
statement	21	21	100.0
branch	4	8	50.0
condition			n/a
subroutine	6	6	100.0
pod			n/a
total	31	35	88.5

package DBIx::Simple::OO;

use strict;
use vars qw[$VERSION];

$VERSION = 0.03;

=head1 NAME

DBIx::Simple::OO

=head1 SYNOPSIS

    use DBIx::Simple;
    use DBIx::Simple::OO;           # adds OO methods

    $db     = DBIx::Simple->connect( ... );
    $query  = 'select id,name,age from people';

    $res    = $db->query( $query );

    $obj    = $res->object;
    @obj    = $res->objects;

    $id     = $obj->id;             # get the value for field 'id'
    $name   = $obj->name;           # get the value for field 'name'
    $age    = $obj->age;            # get the value for field 'age'

    @acc    = $obj->ls_accessors;   # get a list of all fields
    $sub    = $obj->can('name');    # check if this object has a
                                    # 'name' method

    ### add a method to every object that will be returned
    ### by DBIx::Simple::OO
    {   package DBIx::Simple::OO::Item;
        sub has_valid_id { return shift->id !~ /\D/ ? 1 : 0 }
    }
    $bool   = $obj->has_valid_id;

=head1 DESCRIPTION

This module provides a possibility to retrieve rows from a
database as objects, rather than the traditional C
or C. This provides all the usual benefits of using
objects over plain references for accessing data, as well as
allowing you to add methods of your own choosing for data
retrieval.

=head1 HOW IT WORKS

C declares it's 2 methods in the C
namespace, transforming the rows retrieved from the database to
full fledged objects.

=cut

### the retrieval methods are in the DBIx::Simple::Result package

package # hide from PAUSE
  DBIx::Simple::Result;

=head1 METHODS

This module subclasses C and only adds the following
methods. Any other method, like the C call should be looked up
in the C manpage instead.

=head2 $obj = = $db->query(....)->object( );

Returns the first result from your query as an object.

=cut

sub object {
    my $self = shift or return;

    return $self->_href_to_obj( $self->hash );
}

=head2 @objs = $db->query(....)->objects( );

Returns the results from your query as a list of objects.

=cut

sub objects {
    my $self = shift or return;

    return map { $self->_href_to_obj( $_ ) } $self->hashes;
}

### convert the hashref to a nice O::A object
sub _href_to_obj {
    my $self = shift or return;
    my $href = shift or return;

    my $obj  = DBIx::Simple::OO::Item->new;

    ### create accessors for every hash key
    $obj->mk_accessors( keys %$href );

    ### and set the value
    for my $acc ( $obj->ls_accessors ) {
        $obj->$acc( $href->{$acc} );
    }

    return $obj;
}

=head1 ACCESSORS

All objects returned by the above methods are from the
C class, which subclasses
C.

The most important methods are described in the synopsis, but
you should refer to the C manpage for more
extensive documentation.

Note that it is possible to declare methods into the
C class to extend the functionality
of the objects returned by C, as also
described in the C

=cut

### a full on inherited O::A class
package DBIx::Simple::OO::Item;

use base 'Object::Accessor';

1;

=head1 BUG REPORTS

Please report bugs or other issues to [e-mail].

=head1 AUTHOR

This module by Jos Boumans [e-mail].

=head1 COPYRIGHT

This library is free software; you may redistribute and/or modify it
under the same terms as Perl itself.
=cut