-=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.
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:
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',
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