Added perldoc

diff --git a/lib/DBIx/Class/ResultSet/WithMetaData.pm b/lib/DBIx/Class/ResultSet/WithMetaData.pm
index 9cb3c86..ce7be9b 100644 (file)
--- 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<DBIx::Class::ResultClass::HashRefInflator> 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</add_row_info>.
+
+=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</display>.
+
+=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;