=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
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 C<add_item> and C<next_item> method that "just works". 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;
+ }
+
+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 some 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
=head1 COPYRIGHT AND LICENSE
-Copyright 2008 by Infinity Interactive, Inc.
+Copyright 2009 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
projects / gitmo/Moose.git / blobdiff