From: luke Date: Tue, 26 May 2009 14:44:46 +0000 (+0000) Subject: Added perldoc X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=683ececb7f8c1520a637c2c9712f1d7761fd7d73;p=dbsrgits%2FDBIx-Class-ResultSet-WithMetaData.git Added perldoc --- diff --git a/lib/DBIx/Class/ResultSet/WithMetaData.pm b/lib/DBIx/Class/ResultSet/WithMetaData.pm index 9cb3c86..ce7be9b 100644 --- a/lib/DBIx/Class/ResultSet/WithMetaData.pm +++ b/lib/DBIx/Class/ResultSet/WithMetaData.pm @@ -9,85 +9,211 @@ use MooseX::Method::Signatures; extends 'DBIx::Class::ResultSet'; has '_row_info' => ( - is => 'rw', - isa => 'HashRef' + is => 'rw', + isa => 'HashRef' ); has 'was_row' => ( - is => 'rw', - isa => 'Int' + is => 'rw', + isa => 'Int' ); has 'id_cols' => ( - is => 'rw', - isa => 'ArrayRef', + is => 'rw', + isa => 'ArrayRef', ); - + +=head1 VERSION + +Version 0.999001 + +=cut + +our $VERSION = '0.999001'; + +=head1 NAME + +DBIx::Class::ResultSet::WithMetaData + +=head1 SYNOPSIS + + package MyApp::Schema::ResultSet::ObjectType; + + use Moose; + use MooseX::Method::Signatures; + extends 'DBIx::Class::ResultSet::WithMetaData; + + method with_substr () { + foreach my $row ($self->all) { + my $substr = substr($row->name, 0, 3); + $self->add_row_info(row => $row, info => { substr => $substr }); + } + return $self; + } + + ... + + + # then somewhere else + + my $object_type_arrayref = $object_type_rs->limit(count => 3)->with_substr->display(); + + # [{ + # 'artistid' => '1', + # 'name' => 'Caterwauler McCrae', + # 'substr' => 'Cat' + # }, + # { + # 'artistid' => '2', + # 'name' => 'Random Boy Band', + # 'substr' => 'Ran' + # }, + # { + # 'artistid' => '3', + # 'name' => 'We Are Goth', + # 'substr' => 'We ' + # }] + +=head1 DESCRIPTION + +Attach metadata to rows by chaining ResultSet methods together. When the ResultSet is +flattened to an ArrayRef the attached metadata is merged with the row hashes to give +a combined 'hash-plus-other-stuff' representation. + +=head1 METHODS + +=cut sub new { - my $self = shift; + my $self = shift; - my $new = $self->next::method(@_); - foreach my $key (qw/_row_info was_row id_cols/) { - alias $new->{$key} = $new->{attrs}{$key}; - } + my $new = $self->next::method(@_); + foreach my $key (qw/_row_info was_row id_cols/) { + alias $new->{$key} = $new->{attrs}{$key}; + } - unless ($new->_row_info) { - $new->_row_info({}); - } + unless ($new->_row_info) { + $new->_row_info({}); + } - unless ($new->id_cols && scalar(@{$new->id_cols})) { - $new->id_cols([sort $new->result_source->primary_columns]); - } + unless ($new->id_cols && scalar(@{$new->id_cols})) { + $new->id_cols([sort $new->result_source->primary_columns]); + } - return $new; + return $new; } +=head2 display + +=over 4 + +=item Arguments: none + +=item Return Value: ArrayRef + +=back + + $arrayref_of_row_hashrefs = $rs->display(); + +This method uses L to convert all +rows in the ResultSet to HashRefs. These are then merged with any metadata +that had been attached to the rows using L. + +=cut + method display () { my $rs = $self->search({}); $rs->result_class('DBIx::Class::ResultClass::HashRefInflator'); my @rows; - foreach my $row ($rs->all) { - if (my $info = $self->row_info_for(id => $self->_mk_id(row => $row))) { - $row = { %{$row}, %{$info} }; - } - push(@rows, $row); - } + foreach my $row ($rs->all) { + if (my $info = $self->row_info_for(id => $self->_mk_id(row => $row))) { + $row = { %{$row}, %{$info} }; + } + push(@rows, $row); + } return ($self->was_row) ? $rows[0] : \@rows; } +=head2 add_row_info + +=over 4 + +=item Arguments: row => DBIx::Class::Row object, info => HashRef to attach to the row + +=item Return Value: ResultSet + +=back + + $rs = $rs->add_row_info(row => $row, info => { dates => [qw/mon weds fri/] } ); + +This method allows you to attach a HashRef of metadata to a row which will be merged +with that row when the ResultSet is flattened to a datastructure with L. + +=cut + method add_row_info (Int :$id, :$row, HashRef :$info) { - if ($row) { - $id = $self->_mk_id(row => { $row->get_columns }); - } - unless ($self->find($id)) { - warn $id; - die 'invalid id passed to add_row_info'; - } - - if (my $existing = $self->_row_info->{$id}) { - $info = { %{$existing}, %{$info} }; - } - - $self->_row_info->{$id} = $info; + if ($row) { + $id = $self->_mk_id(row => { $row->get_columns }); + } + unless ($self->find($id)) { + die 'invalid id passed to add_row_info'; + } + + if (my $existing = $self->_row_info->{$id}) { + $info = { %{$existing}, %{$info} }; + } + + $self->_row_info->{$id} = $info; } method row_info_for (Int :$id) { - return $self->_row_info->{$id}; + return $self->_row_info->{$id}; } +=head2 order_by (EXPERIMENTAL) + +=over 4 + +=item Arguments: col => $column_name + +=item Return Value: ResultSet + +=back + + $ordered_rs = $rs->order_by(col => 'name'); + +Convenience method. Essentually a shortcut for $rs->search({}, { order_by => $col }). + +=cut + method order_by (Str :$col) { - $col = "me.$col" unless ($col =~ m/\./); - return $self->search({}, { order_by => $col }); + $col = "me.$col" unless ($col =~ m/\./); + return $self->search({}, { order_by => $col }); } +=head2 limit (EXPERIMENTAL) + +=over 4 + +=item Arguments: count => Int + +=item Return Value: ResultSet + +=back + + $limitted_rs = $rs->limit(count => 3); + +Convenience method. Essentually a shortcut for $rs->search({}, { rows => $count }). + +=cut + method limit (Int :$count) { - return $self->search({}, { rows => $count }); + return $self->search({}, { rows => $count }); } method _mk_id (HashRef :$row) { - return join('-', map { $row->{$_} } @{$self->id_cols}); + return join('-', map { $row->{$_} } @{$self->id_cols}); } 1;