add proof reading changes from dec

[gitmo/Moose.git] / lib / Moose / Manual / Delegation.pod

diff --git a/lib/Moose/Manual/Delegation.pod b/lib/Moose/Manual/Delegation.pod
index 306a5f9..ee41c10 100644 (file)
--- a/lib/Moose/Manual/Delegation.pod
+++ b/lib/Moose/Manual/Delegation.pod
@@ -2,22 +2,22 @@
 
 =head1 NAME
 
-Moose::Manual::Attribute - Attribute Delegation
+Moose::Manual::Delegation - Attribute delegation
 
 =head1 WHAT IS DELEGATION?
 
-Moose's delegation feature lets you create "shadow" 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"
+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.
 
-This means that consumers of a class don't need to know about all the
-objects it contains, and it simplifies their code.
+With delegation, consumers of a class don't need to know about all the
+objects it contains, reducing the amount of API they need to learn.
 
 Delegations are defined as a mapping between one or more methods
 provided by the "real" class (the delegatee), and a set of
 corresponding methods in the delegating class. The delegating class
-can re-use the method names provided by the delegatee, or provide its
+can re-use the method names provided by the delegatee or provide its
 own names.
 
 Delegation is also a great way to wrap an existing class, especially a
@@ -94,11 +94,63 @@ 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 mechanism is very
+similar. 
+ 
+  has 'queue' => (
+      isa => 'ArrayRef[Item]',
+      traits => ['Array'],
+      default => sub { [ ] },
+      handles => {
+          add_item => 'push',
+          next_item => 'shift',
+      }
+  )
+
+By providing the 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 definition, 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
-required, or can be undefined. In that case, Moose will throw a
-runtime error when a delegated method is called.
+required or can be undefined. When a delegated method is called, Moose
+will throw a runtime error if the attribute does not contain an
+object.
 
 =head1 AUTHOR
 
@@ -106,7 +158,7 @@ Dave Rolsky E<lt>autarch@urth.orgE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2008 by Infinity Interactive, Inc.
+Copyright 2009 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>