X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FManual%2FDelegation.pod;h=29ded4eac47a998cf1b97a7e048001e120d6ec03;hb=25a19dffe45b4a14ae23a4aea9b91e872f78e825;hp=e0a5d09b95e8f478b1048f4d328f885962a86e59;hpb=a07ac19685f4b014984a9af3aa654640a2884695;p=gitmo%2FMoose.git

diff --git a/lib/Moose/Manual/Delegation.pod b/lib/Moose/Manual/Delegation.pod
index e0a5d09..29ded4e 100644
--- a/lib/Moose/Manual/Delegation.pod
+++ b/lib/Moose/Manual/Delegation.pod
@@ -1,15 +1,17 @@
-=pod
+package Moose::Manual::Delegation;
+
+# ABSTRACT: Attribute delegation
 
-=head1 NAME
+__END__
 
-Moose::Manual::Delegation - Attribute delegation
+=pod
 
 =head1 WHAT IS DELEGATION?
 
-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.
+Delegation is a feature that lets you create "proxy" methods that do nothing
+more than call some other method on an attribute. This lets you simplify a
+complex set of "has-a" relationships and present a single unified API from one
+class.
 
 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.
@@ -43,7 +45,8 @@ The simplest form is to simply specify a list of methods:
 
 With this definition, we can call C<< $website->host >> and it "just
 works". Under the hood, Moose will call C<< $website->uri->host >> for
-you.
+you. Note that C<$website> is not automatically passed to the C<host>
+method; the invocant is C<< $website->uri >>.
 
 We can also define a mapping as a hash reference. This allows you to
 rename methods as part of the mapping:
@@ -65,7 +68,7 @@ In this example, we've created a C<< $website->hostname >> method,
 rather than using C<URI.pm>'s name, C<host>.
 
 These two mapping forms are the ones you will use most often. The
-remainder are a bit more complex, and less common.
+remaining methods are a bit more complex.
 
   has 'uri' => (
       is      => 'ro',
@@ -94,56 +97,79 @@ 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
+=head1 NATIVE DELEGATION
+
+Native delegations allow you to delegate to standard Perl data structures as
+if they were objects.
 
-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'],
+      traits  => ['Array'],
+      isa     => 'ArrayRef[Item]',
       default => sub { [ ] },
       handles => {
-          add_item => 'push',
+          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
+The C<Array> trait in the C<traits> parameter tells Moose that you would like
+to use the set of Array helpers. Moose will then create C<add_item> and
+C<next_item> methods that "just work". Behind the scenes C<add_item> is
+something like
 
-  sub add_item { 
+  sub add_item {
       my ($self, @items) = @_;
+
+      for my $item (@items) {
+          $Item_TC->validate($item);
+      }
+
       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>.
+Moose includes the following traits for native delegation:
+
+=over 4
+
+=item * L<Array|Moose::Meta::Attribute::Native::Trait::Array>
+
+=item * L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
+
+=item * L<Code|Moose::Meta::Attribute::Native::Trait::Code>
+
+=item * L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
+
+=item * L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
+
+=item * L<Number|Moose::Meta::Attribute::Native::Trait::Number>
+
+=item * L<String|Moose::Meta::Attribute::Native::Trait::String>
+
+=back
 
 =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. 
+Currying allows you to create a method with some pre-set parameters. You can
+create a curried delegation method:
 
     package Spider;
     use Moose;
 
     has request => (
-        is => 'ro'
-        isa => 'HTTP::Request',
+        is      => 'ro'
+        isa     => 'HTTP::Request',
         handles => {
-            set_user_agent => [ header => 'UserAgent'],
-        }
+            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')>.
+With this definition, calling C<< $spider->set_user_agent('MyClient') >> will
+call C<< $spider->request->header('UserAgent', 'MyClient') >> behind the
+scenes.
+
+Note that with currying, the currying always starts with the first parameter to
+a method (C<$_[0]>). Any arguments you pass to the delegation come after the
+curried arguments.
 
 =head1 MISSING ATTRIBUTES
 
@@ -152,17 +178,4 @@ 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
-
-Dave Rolsky E<lt>autarch@urth.orgE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2009 by Infinity Interactive, Inc.
-
-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