Commit | Line | Data |
093a09aa |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
d67ce58f |
5 | Moose::Manual::Delegation - Attribute delegation |
093a09aa |
6 | |
7 | =head1 WHAT IS DELEGATION? |
8 | |
50f346d7 |
9 | Delegation is a feature that lets you create "proxy" methods that |
117ad31b |
10 | do nothing more than call some other method on an attribute. This |
d3e02c74 |
11 | is quite handy since it lets you simplify a complex set of "has-a" |
093a09aa |
12 | relationships and present a single unified API from one class. |
13 | |
d3e02c74 |
14 | With delegation, consumers of a class don't need to know about all the |
15 | objects it contains, reducing the amount of API they need to learn. |
093a09aa |
16 | |
17 | Delegations are defined as a mapping between one or more methods |
18 | provided by the "real" class (the delegatee), and a set of |
19 | corresponding methods in the delegating class. The delegating class |
d3e02c74 |
20 | can re-use the method names provided by the delegatee or provide its |
093a09aa |
21 | own names. |
22 | |
23 | Delegation is also a great way to wrap an existing class, especially a |
24 | non-Moose class or one that is somehow hard (or impossible) to |
25 | subclass. |
26 | |
27 | =head1 DEFINING A MAPPING |
28 | |
29 | Moose offers a number of options for defining a delegation's mapping, |
30 | ranging from simple to complex. |
31 | |
32 | The simplest form is to simply specify a list of methods: |
33 | |
34 | package Website; |
35 | |
36 | use Moose; |
37 | |
38 | has 'uri' => ( |
39 | is => 'ro', |
40 | isa => 'URI', |
41 | handles => [qw( host path )], |
42 | ); |
43 | |
44 | With this definition, we can call C<< $website->host >> and it "just |
45 | works". Under the hood, Moose will call C<< $website->uri->host >> for |
46 | you. |
47 | |
48 | We can also define a mapping as a hash reference. This allows you to |
49 | rename methods as part of the mapping: |
50 | |
51 | package Website; |
52 | |
53 | use Moose; |
54 | |
55 | has 'uri' => ( |
56 | is => 'ro', |
57 | isa => 'URI', |
58 | handles => { |
59 | hostname => 'host', |
60 | path => 'path', |
61 | }, |
62 | ); |
63 | |
64 | In this example, we've created a C<< $website->hostname >> method, |
65 | rather than using C<URI.pm>'s name, C<host>. |
66 | |
67 | These two mapping forms are the ones you will use most often. The |
68 | remainder are a bit more complex, and less common. |
69 | |
70 | has 'uri' => ( |
71 | is => 'ro', |
72 | isa => 'URI', |
73 | handles => qr/^(?:host|path|query.*)/, |
74 | ); |
75 | |
76 | This is similar to the array version, except it uses the regex to |
77 | match against all the methods provided by the delegatee. In order for |
78 | this to work, you must provide an C<isa> parameter for the attribute, |
79 | and it must be a class. Moose uses this to introspect the delegatee |
80 | class and determine what methods it provides. |
81 | |
82 | You can use a role name as the value of C<handles>: |
83 | |
84 | has 'uri' => ( |
85 | is => 'ro', |
86 | isa => 'URI', |
87 | handles => 'HasURI', |
88 | ); |
89 | |
90 | Moose will introspect the role to determine what methods it provides |
91 | and create a mapping for each of those methods. |
92 | |
93 | Finally, you can also provide a sub reference to I<generate> a |
94 | mapping. You probably won't need this version often (if ever). See the |
95 | L<Moose> docs for more details on exactly how this works. |
96 | |
50f346d7 |
97 | =head1 PERL DATA STRUCTURES |
98 | |
99 | Handles also will allow you to delegate to "helper" methods that work on |
100 | common Perl data structures. If you remember or have ever used |
a07ac196 |
101 | L<MooseX::AttributeHelpers|MooseX::AttributeHelpers> the mechanism is very |
f4c5daeb |
102 | similar. |
103 | |
50f346d7 |
104 | has 'queue' => ( |
f4c5daeb |
105 | isa => 'ArrayRef[Item]', |
106 | traits => ['Array'], |
50f346d7 |
107 | default => sub { [ ] }, |
108 | handles => { |
f4c5daeb |
109 | add_item => 'push', |
50f346d7 |
110 | next_item => 'shift', |
9610c1d2 |
111 | }, |
50f346d7 |
112 | ) |
113 | |
f4c5daeb |
114 | By providing the C<Array> trait to the C<traits> parameter you signal to |
50f346d7 |
115 | Moose that you would like to use the set of Array helpers. Moose will then |
8580644d |
116 | create C<add_item> and C<next_item> method that "just works". Behind the |
50f346d7 |
117 | scenes C<add_item> is something like |
118 | |
f4c5daeb |
119 | sub add_item { |
50f346d7 |
120 | my ($self, @items) = @_; |
26366034 |
121 | |
f4c5daeb |
122 | for my $item (@items) { |
123 | $Item_TC->validate($item); |
124 | } |
26366034 |
125 | |
50f346d7 |
126 | push @{ $self->queue }, @items; |
127 | } |
128 | |
129 | There are traits for not only C<Array> but also C<Hash>, C<Bool>, C<String>, |
130 | C<Number>, and C<Counter>. For more information see the documentation in |
131 | L<Moose::Meta::Attribute::Native|Moose::Meta::Attribute::Native>. |
132 | |
133 | =head1 CURRYING |
134 | |
135 | Currying is a way of creating a method or function from another method or |
26366034 |
136 | function with some of the parameters pre-defined. Moose provides the ability to |
f4c5daeb |
137 | curry methods when creating delegates. |
50f346d7 |
138 | |
139 | package Spider; |
140 | use Moose; |
141 | |
142 | has request => ( |
26366034 |
143 | is => 'ro' |
144 | isa => 'HTTP::Request', |
50f346d7 |
145 | handles => { |
26366034 |
146 | set_user_agent => [ header => 'UserAgent' ], |
9610c1d2 |
147 | }, |
50f346d7 |
148 | ) |
149 | |
8580644d |
150 | With this definition, calling C<< $spider->set_user_agent('MyClient') >> will |
4a1fdc05 |
151 | behind the scenes call C<< $spider->request->header('UserAgent', 'MyClient') >>. |
50f346d7 |
152 | |
093a09aa |
153 | =head1 MISSING ATTRIBUTES |
154 | |
155 | It is perfectly valid to delegate methods to an attribute which is not |
d3e02c74 |
156 | required or can be undefined. When a delegated method is called, Moose |
157 | will throw a runtime error if the attribute does not contain an |
158 | object. |
093a09aa |
159 | |
160 | =head1 AUTHOR |
161 | |
162 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
163 | |
164 | =head1 COPYRIGHT AND LICENSE |
165 | |
2840a3b2 |
166 | Copyright 2009 by Infinity Interactive, Inc. |
093a09aa |
167 | |
168 | L<http://www.iinteractive.com> |
169 | |
170 | This library is free software; you can redistribute it and/or modify |
171 | it under the same terms as Perl itself. |
172 | |
173 | =cut |