-=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.
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
+
+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
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
projects / gitmo/Moose.git / blobdiff