Commit | Line | Data |
093a09aa |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
5 | Moose::Manual::Attribute - Attribute Delegation |
6 | |
7 | =head1 WHAT IS DELEGATION? |
8 | |
d3e02c74 |
9 | Delegation is a feature that lets you create create "shadow" methods |
10 | that do nothing more than call some other method on an attribute. This |
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 | |
97 | =head1 MISSING ATTRIBUTES |
98 | |
99 | It is perfectly valid to delegate methods to an attribute which is not |
d3e02c74 |
100 | required or can be undefined. When a delegated method is called, Moose |
101 | will throw a runtime error if the attribute does not contain an |
102 | object. |
093a09aa |
103 | |
104 | =head1 AUTHOR |
105 | |
106 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
107 | |
108 | =head1 COPYRIGHT AND LICENSE |
109 | |
110 | Copyright 2008 by Infinity Interactive, Inc. |
111 | |
112 | L<http://www.iinteractive.com> |
113 | |
114 | This library is free software; you can redistribute it and/or modify |
115 | it under the same terms as Perl itself. |
116 | |
117 | =cut |