=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.
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 PERL DATA STRUCTURES
+=head1 NATIVE DELEGATION
-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.
+Native delegations allow you to delegate to standard Perl data structures as
+if they were objects.
has 'queue' => (
- isa => 'ArrayRef[Item]',
traits => ['Array'],
+ isa => 'ArrayRef[Item]',
default => sub { [ ] },
handles => {
add_item => 'push',
},
)
-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
+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) = @_;
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 some 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;
)
With this definition, calling C<< $spider->set_user_agent('MyClient') >> will
-behind the scenes call C<< $spider->request->header('UserAgent', 'MyClient')>>.
+call C<< $spider->request->header('UserAgent', 'MyClient') >> behind the
+scenes.
+
+Note that with currying, the currying always start with the first parameter to
+a method (C<$_[0]>). Any arguments you pass to the delegation come after the
+curried arguments.
=head1 MISSING ATTRIBUTES
=head1 COPYRIGHT AND LICENSE
-Copyright 2009 by Infinity Interactive, Inc.
+Copyright 2009-2010 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>