add documentation on the new AH delegation (Currying and Perl Data Structures)

diff --git a/lib/Moose/Manual/Delegation.pod b/lib/Moose/Manual/Delegation.pod
index 359acd4..0203892 100644 (file)
--- a/lib/Moose/Manual/Delegation.pod
+++ b/lib/Moose/Manual/Delegation.pod
@@ -6,7 +6,7 @@ Moose::Manual::Delegation - Attribute delegation
 
 =head1 WHAT IS DELEGATION?
 
-Delegation is a feature that lets you create "shadow" methods that
+Delegation is a feature that lets you create "proxy" methods that
 do nothing more than call some other method on an attribute. This
 is quite handy since it lets you simplify a complex set of "has-a"
 relationships and present a single unified API from one class.
@@ -94,6 +94,57 @@ Finally, you can also provide a sub reference to I<generate> a
 mapping. You probably won't need this version often (if ever). See the
 L<Moose> docs for more details on exactly how this works.
 
+=head1 PERL DATA STRUCTURES
+
+Handles also will allow you to delegate to "helper" methods that work on
+common Perl data structures. If you remember or have ever used
+L<MooseX::AttributeHelpers|MooseX::AttributeHelpers> the mechanisim is very
+similar. 
+ 
+  has 'queue' => (
+      isa => 'ArrayRef[Item]',
+      traits => ['Array'],
+      default => sub { [ ] },
+      handles => {
+          add_item => 'push',
+          next_item => 'shift',
+      }
+  )
+
+By providing using C<Array> trait to the C<traits> parameter you signal to
+Moose that you would like to use the set of Array helpers. Moose will then
+create an C<add_item> and a C<next_item> method that "just works". Behind the
+scenes C<add_item> is something like
+
+  sub add_item { 
+      my ($self, @items) = @_;
+      push @{ $self->queue }, @items;
+  }
+
+There are traits for not only C<Array> but also C<Hash>, C<Bool>, C<String>,
+C<Number>, and C<Counter>. For more information see the documentation in
+L<Moose::Meta::Attribute::Native|Moose::Meta::Attribute::Native>.
+
+=head1 CURRYING
+
+Currying is a way of creating a method or function from another method or
+function with one of the parameters pre-defined. Moose provides the ability to
+curry methods when creating delegates. 
+
+    package Spider;
+    use Moose;
+
+    has request => (
+        is => 'ro'
+        isa => 'HTTP::Request',
+        handles => {
+            set_user_agent => [ header => 'UserAgent'],
+        }
+    )
+
+With this definiton calling C<$spider->set_user_agent('MyClient')> will behind
+the scenes call C<$spider->request->header('UserAgent', 'MyClient')>. 
+
 =head1 MISSING ATTRIBUTES
 
 It is perfectly valid to delegate methods to an attribute which is not