some POD advances

[gitmo/MooseX-AttributeHelpers.git] / lib / MooseX / AttributeHelpers.pm

diff --git a/lib/MooseX/AttributeHelpers.pm b/lib/MooseX/AttributeHelpers.pm
index dddde08..ad9e9be 100644 (file)
--- a/lib/MooseX/AttributeHelpers.pm
+++ b/lib/MooseX/AttributeHelpers.pm
@@ -19,12 +19,68 @@ __END__
 
 =head1 NAME
 
-MooseX::AttributeHelpers 
+MooseX::AttributeHelpers - Extend your attribute interfaces
 
 =head1 SYNOPSIS
 
+  package MyClass;
+  use Moose;
+
+  has mapping => (
+      metaclass => 'Collection::Hash',
+      is        => 'rw',
+      isa       => 'HashRef',
+      default   => sub { {} },
+      provides  => {
+          exists    => 'exists_in_mapping',
+          keys      => 'ids_in_mapping',
+          get       => 'get_mapping',
+          set       => 'set_mapping',
+      },
+  );
+
+  # ...
+
+  my $obj = MyClass->new;
+  $obj->set_mapping(4, 'foo');
+  $obj->set_mapping(5, 'bar');
+  $obj->set_mapping(6, 'baz');
+
+  # prints 'bar'
+  print $obj->get_mapping(5) if $obj->exists_in_mapping(5);
+
+  # prints '4, 5, 6'
+  print join ', ', $obj->ids_in_mapping;
+
 =head1 DESCRIPTION
 
+While L<Moose> attributes provide you with a way to name your accessors,
+readers, writers, clearers and predicates, this library provides commonly
+used attribute helper methods for more specific types of data.
+
+As seen in the L</SYNOPSIS>, you specify the extension via the 
+C<metaclass> parameter. Available meta classes are:
+
+=over
+
+=item L<Number|MooseX::AttributeHelpers::Number>
+
+Common numerical operations.
+
+=item L<Counter|MooseX::AttributeHelpers::Counter>
+
+Methods for incrementing and decrementing a counter attribute.
+
+=item L<Collection::Hash|MooseX::AttributeHelpers::Collection::Hash>
+
+Common methods for hash references.
+
+=item L<Collection::Array|MooseX::AttributeHelpers::Collection::Array>
+
+Common methods for array references.
+
+=back
+
 =head1 BUGS
 
 All complex software has bugs lurking in it, and this module is no 
@@ -44,4 +100,4 @@ L<http://www.iinteractive.com>
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself.
 
-=cut
\ No newline at end of file
+=cut