1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
=pod
=head1 NAME
Moose::Cookbook::Meta::Recipe3 - Labels implemented via attribute traits
=head1 SYNOPSIS
package MyApp::Meta::Attribute::Trait::Labeled;
use Moose::Role;
has label => (
is => 'rw',
isa => 'Str',
predicate => 'has_label',
);
package Moose::Meta::Attribute::Custom::Trait::Labeled;
sub register_implementation {'MyApp::Meta::Attribute::Trait::Labeled'}
package MyApp::Website;
use Moose;
has url => (
traits => [qw/Labeled/],
is => 'rw',
isa => 'Str',
label => "The site's URL",
);
has name => (
is => 'rw',
isa => 'Str',
);
sub dump {
my $self = shift;
my $meta = $self->meta;
my $dump = '';
for my $attribute ( map { $meta->get_attribute($_) }
sort $meta->get_attribute_list ) {
if ( $attribute->does('MyApp::Meta::Attribute::Trait::Labeled')
&& $attribute->has_label ) {
$dump .= $attribute->label;
}
else {
$dump .= $attribute->name;
}
my $reader = $attribute->get_read_method;
$dump .= ": " . $self->$reader . "\n";
}
return $dump;
}
package main;
my $app = MyApp::Website->new( url => "http://google.com", name => "Google" );
=head1 BUT FIRST
This recipe is a variation on
L<Moose::Cookbook::Meta::Recipe2>. Please read that recipe first.
=head1 MOTIVATION
In L<Moose::Cookbook::Meta::Recipe2>, we created an attribute
metaclass which lets you provide a label for attributes.
Using a metaclass works fine until you realize you want to add a label
I<and> an expiration, or some other combination of new behaviors. You
could create yet another metaclass which subclasses those two, but
that makes a mess, especially if you want to mix and match behaviors
across many attributes.
Fortunately, Moose provides a much saner alternative, which is to
encapsulate each extension as a role, not a class. We can make a role
which adds a label to an attribute, and could make another to
implement expiration.
=head1 TRAITS
Roles that apply to metaclasses have a special name: traits. Don't let
the change in nomenclature fool you, B<traits are just roles>.
L<Moose/has> allows you to pass a C<traits> parameter for an
attribute. This parameter takes a list of trait names which are
composed into an anonymous metaclass, and that anonymous metaclass is
used for the attribute.
Yes, we still have lots of metaclasses in the background, but they're
managed by Moose for you.
Traits can do anything roles can do. They can add or refine
attributes, wrap methods, provide more methods, define an interface,
etc. The only difference is that you're now changing the attribute
metaclass instead of a user-level class.
=head1 DISSECTION
A side-by-side look of the code examples in this recipe and recipe 2
show that defining and using a trait is very similar to a full-blown
metaclass.
package MyApp::Meta::Attribute::Trait::Labeled;
use Moose::Role;
has label => (
is => 'rw',
isa => 'Str',
predicate => 'has_label',
);
Instead of subclassing L<Moose::Meta::Attribute>, we define a role. As
with our metaclass in L<recipe 2|Moose::Cookbook::Meta::Recipe2>,
registering our role allows us to refer to it by a short name.
package Moose::Meta::Attribute::Custom::Trait::Labeled;
sub register_implementation { 'MyApp::Meta::Attribute::Trait::Labeled' }
Moose looks for the C<register_implementation> method in
C<Moose::Meta::Attribute::Custom::Trait::$TRAIT_NAME> to find the full
name of the trait.
For the rest of the code, we will only cover what is I<different> from
L<recipe 2|Moose::Cookbook::Meta::Recipe2>.
has url => (
traits => [qw/Labeled/],
is => 'rw',
isa => 'Str',
label => "The site's URL",
);
Instead of passing a C<metaclass> parameter, this time we pass
C<traits>. This contains a list of trait names. Moose will build an
anonymous attribute metaclass from these traits and use it for this
attribute. Passing a C<label> parameter works just as it did with the
metaclass example.
if ( $attribute->does('MyApp::Meta::Attribute::Trait::Labeled')
&& $attribute->has_label ) {
$dump .= $attribute->label;
}
In the metaclass example, we used C<< $attribute->isa >>. With a role,
we instead ask if the meta-attribute object C<does> the required
role. If it does not do this role, the attribute meta object won't
have the C<has_label> method.
That's all. Everything else is the same!
=head1 TURNING A METACLASS INTO A TRAIT
"But wait!" you protest. "I've already written all of my extensions as
attribute metaclasses. I don't want to break all that code out there."
Fortunately, you can easily turn a metaclass into a trait and still
provide the original metaclass:
package MyApp::Meta::Attribute::Labeled;
use Moose;
extends 'Moose::Meta::Attribute';
with 'MyApp::Meta::Attribute::Trait::Labeled';
package Moose::Meta::Attribute::Custom::Labeled;
sub register_implementation { 'MyApp::Meta::Attribute::Labeled' }
Unfortunately, going the other way (providing a trait created from a
metaclass) is more tricky.
=head1 CONCLUSION
If you're extending your attributes, it's easier and more flexible to
provide composable bits of behavior than to subclass
L<Moose::Meta::Attribute>. Using traits lets you cooperate with other
extensions, either from CPAN or that you might write in the
future. Moose makes it easy to create attribute metaclasses on the fly
by providing a list of trait names to L<Moose/has>.
=head1 AUTHOR
Shawn M Moore E<lt>sartak@gmail.comE<gt>
Dave Rolsky E<lt>autarch@urth.org<gt>
=head1 COPYRIGHT AND LICENSE
Copyright 2006-2010 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.
=begin testing
my $app2
= MyApp::Website->new( url => "http://google.com", name => "Google" );
is(
$app2->dump, q{name: Google
The site's URL: http://google.com
}, '... got the expected dump value'
);
=end testing
=cut
|
