Require Dist::Zilla 4.200016+

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

diff --git a/lib/Moose/Manual/Delegation.pod b/lib/Moose/Manual/Delegation.pod
index 804f7f9..29ded4e 100644 (file)
--- 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::Attribute - Attribute Delegation
+=pod
 
 =head1 WHAT IS DELEGATION?
 
-Delegation is a feature that lets you create 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"
-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,24 +97,85 @@ 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 MISSING ATTRIBUTES
+=head1 NATIVE DELEGATION
 
-It is perfectly valid to delegate methods to an attribute which is not
-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.
+Native delegations allow you to delegate to standard Perl data structures as
+if they were objects.
+
+  has 'queue' => (
+      traits  => ['Array'],
+      isa     => 'ArrayRef[Item]',
+      default => sub { [ ] },
+      handles => {
+          add_item  => 'push',
+          next_item => 'shift',
+      },
+  )
+
+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 {
+      my ($self, @items) = @_;
+
+      for my $item (@items) {
+          $Item_TC->validate($item);
+      }
+
+      push @{ $self->queue }, @items;
+  }
+
+Moose includes the following traits for native delegation:
 
-=head1 AUTHOR
+=over 4
 
-Dave Rolsky E<lt>autarch@urth.orgE<gt>
+=item * L<Array|Moose::Meta::Attribute::Native::Trait::Array>
 
-=head1 COPYRIGHT AND LICENSE
+=item * L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
 
-Copyright 2008 by Infinity Interactive, Inc.
+=item * L<Code|Moose::Meta::Attribute::Native::Trait::Code>
 
-L<http://www.iinteractive.com>
+=item * L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
 
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
+=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 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',
+        handles => {
+            set_user_agent => [ header => 'UserAgent' ],
+        },
+    )
+
+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
+
+It is perfectly valid to delegate methods to an attribute which is not
+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.
 
 =cut