merge trunk to pluggable errors
[gitmo/Moose.git] / lib / Moose / Cookbook / Meta / Recipe2.pod
1
2 =pod
3
4 =head1 NAME
5
6 Moose::Cookbook::Meta::Recipe2 - A meta-attribute, attributes with labels
7
8 =head1 SYNOPSIS
9
10     package MyApp::Meta::Attribute::Labeled;
11     use Moose;
12     extends 'Moose::Meta::Attribute';
13
14     has label => (
15         is  => 'rw',
16         isa => 'Str',
17         predicate => 'has_label',
18     );
19
20     package Moose::Meta::Attribute::Custom::Labeled;
21     sub register_implementation { 'MyApp::Meta::Attribute::Labeled' }
22
23     package MyApp::Website;
24     use Moose;
25     use MyApp::Meta::Attribute::Labeled;
26
27     has url => (
28         metaclass => 'Labeled',
29         is        => 'rw',
30         isa       => 'Str',
31         label     => "The site's URL",
32     );
33
34     has name => (
35         is  => 'rw',
36         isa => 'Str',
37     );
38
39     sub dump {
40         my $self = shift;
41
42         # iterate over all the attributes in $self
43         my %attributes = %{ $self->meta->get_attribute_map };
44         while (my ($name, $attribute) = each %attributes) {
45
46             # print the label if available
47             if ($attribute->isa('MyApp::Meta::Attribute::Labeled')
48                 && $attribute->has_label) {
49                     print $attribute->label;
50             }
51             # otherwise print the name
52             else {
53                 print $name;
54             }
55
56             # print the attribute's value
57             my $reader = $attribute->get_read_method;
58             print ": " . $self->$reader . "\n";
59         }
60     }
61
62     package main;
63     my $app = MyApp::Website->new(url => "http://google.com", name => "Google");
64     $app->dump;
65
66 =head1 SUMMARY
67
68 In this recipe, we begin to really delve into the wonder of meta-programming.
69 Some readers may scoff and claim that this is the arena only of the most
70 twisted Moose developers. Absolutely not! Any sufficiently twisted developer
71 can benefit greatly from going more meta.
72
73 The high-level goal of this recipe's code is to allow each attribute to have a
74 human-readable "label" attached to it. Such labels would be used when showing
75 data to an end user. In this recipe we label the "url" attribute with "The
76 site's URL" and create a simple method to demonstrate how to use that label.
77
78 =head1 REAL ATTRIBUTES 101
79
80 All the attributes of a Moose-based object are actually objects themselves.
81 These objects have methods and (surprisingly) attributes. Let's look at a
82 concrete example.
83
84     has 'x' => (isa => 'Int', is => 'ro');
85     has 'y' => (isa => 'Int', is => 'rw');
86
87 Ahh, the veritable x and y of the Point example. Internally, every Point has an
88 x object and a y object. They have methods (such as "get_value") and attributes
89 (such as "is_lazy"). What class are they instances of?
90 L<Moose::Meta::Attribute>.  You don't normally see the objects lurking behind
91 the scenes, because you usually just use C<< $point->x >> and C<< $point->y >>
92 and forget that there's a lot of machinery lying in such methods.
93
94 So you have a C<$point> object, which has C<x> and C<y> methods. How can you
95 actually access the objects behind these attributes? Here's one way:
96
97     $point->meta->get_attribute_map()
98
99 C<get_attribute_map> returns a hash reference that maps attribute names to
100 their objects. In our case, C<get_attribute_map> might return something that
101 looks like the following:
102
103     {
104         x => Moose::Meta::Attribute=HASH(0x196c23c),
105         y => Moose::Meta::Attribute=HASH(0x18d1690),
106     }
107
108 Another way to get a handle on an attribute's object is
109 C<< $self->meta->get_attribute('name') >>. Here's one thing you can do now that
110 you can interact with the attribute's object directly:
111
112     print $point->meta->get_attribute('x')->type_constraint;
113        => Int
114
115 (As an aside, it's not called C<< ->isa >> because C<< $obj->isa >> is already
116 taken)
117
118 So to actually beef up attributes, what we need to do is:
119
120 =over 4
121
122 =item Create a new attribute metaclass
123
124 =item Create attributes using that new metaclass
125
126 =back
127
128 Moose makes both of these easy!
129
130 Let's start dissecting the recipe's code.
131
132 =head1 DISSECTION
133
134 We get the ball rolling by creating a new attribute metaclass. It starts off
135 somewhat ungloriously.
136
137     package MyApp::Meta::Attribute::Labeled;
138     use Moose;
139     extends 'Moose::Meta::Attribute';
140
141 You subclass metaclasses the same way you subclass regular classes. (Extra
142 credit: how in the actual hell can you use the MOP to extend itself?)
143
144     has label => (
145         is        => 'rw',
146         isa       => 'Str',
147         predicate => 'has_label',
148     );
149
150 Hey, this looks pretty reasonable! This is plain jane Moose code. Recipe 1
151 fare. This is merely making a new attribute. An attribute that attributes have.
152 A meta-attribute. It may sound scary, but it really isn't! Reread
153 L<REAL ATTRIBUTES 101> if this really is terrifying.
154
155 The name is "label", it will have a regular accessor, and is a string.
156 C<predicate> is a standard part of C<has>. It just creates a method that asks
157 the question "Does this attribute have a value?"
158
159     package Moose::Meta::Attribute::Custom::Labeled;
160     sub register_implementation { 'MyApp::Meta::Attribute::Labeled' }
161
162 This lets Moose discover our new metaclass. That way attributes can actually
163 use it. More on what this is doing in a moment.
164
165 Note that we're done defining the new metaclass! Only nine lines of code, and
166 not particularly difficult lines, either. Now to start using the metaclass.
167
168     package MyApp::Website;
169     use Moose;
170     use MyApp::Meta::Attribute::Labeled;
171
172 Nothing new here. We do have to actually load our metaclass to be able to use
173 it.
174
175     has url => (
176         metaclass => 'Labeled',
177         is        => 'rw',
178         isa       => 'Str',
179         label     => "The site's URL",
180     );
181
182 Ah ha! Now we're using the metaclass. We're adding a new attribute, C<url>, to
183 C<MyApp::Website>. C<has> lets you set the metaclass of the attribute.
184 Ordinarily (as we've seen), the metaclass is C<Moose::Meta::Attribute>.
185
186 When C<has> sees that you're using a new metaclass, it will take the
187 metaclass's name, prepend C<Moose::Meta::Attribute::Custom::>, and call the
188 C<register_implementation> function in that package. So here Moose calls
189 C<Moose::Meta::Attribute::Custom::Labeled::register_implementation>. We defined
190 that function in the beginning -- it just returns our "real" metaclass'
191 package, C<MyApp::Meta::Attribute::Labeled>. So Moose uses that metaclass for
192 the attribute. It may seem a bit convoluted, but the alternative would be to
193 use C<< metaclass => 'MyApp::Meta::Attribute::Labeled' >> on every attribute.
194 As usual, Moose optimizes in favor of the end user, not the metaprogrammer. :)
195 We also could have just defined the metaclass in
196 C<Moose::Meta::Attribute::Custom::Labeled>, but it's probably better to keep to
197 your own namespaces.
198
199 Finally, we see that C<has> is setting our new meta-attribute, C<label>, to
200 C<"The site's URL">. We can access this meta-attribute with:
201
202     $website->meta->get_attribute('url')->label()
203
204 Well, back to the code.
205
206     has name => (
207         is  => 'rw',
208         isa => 'Str',
209     );
210
211 Of course, you don't have to use the new metaclass for B<all> new attributes.
212
213 Now we begin defining a method that will dump the C<MyApp::Website> instance
214 for human readers.
215
216     sub dump {
217         my $self = shift;
218
219         # iterate over all the attributes in $self
220         my %attributes = %{ $self->meta->get_attribute_map };
221         while (my ($name, $attribute) = each %attributes) {
222
223 Recall that C<get_attribute_map> returns a hashref of attribute names and their
224 associated objects.
225
226             # print the label if available
227             if ($attribute->isa('MyApp::Meta::Attribute::Labeled')
228                 && $attribute->has_label) {
229                     print $attribute->label;
230             }
231
232 We have two checks here. The first is "is this attribute an instance of
233 C<MyApp::Meta::Attribute::Labeled>?". It's good to code defensively. Even if
234 all of your attributes have this metaclass, you never know when someone is
235 going to subclass your work of art. Poorly. In other words, it's likely that
236 there will still be (many) attributes that are instances of the default
237 C<Moose::Meta::Attribute>.
238
239 The second check is "does this attribute have a label?". This method was
240 defined in the new metaclass as the "predicate". If we pass both checks, we
241 print the attribute's label.
242
243             # otherwise print the name
244             else {
245                 print $name;
246             }
247
248 Another good, defensive coding practice: Provide reasonable defaults.
249
250             # print the attribute's value
251             my $reader = $attribute->get_read_method;
252             print ": " . $self->$reader . "\n";
253         }
254     }
255
256 Here's another example of using the attribute metaclass.
257 C<< $attribute->get_read_method >> returns the name of the method that can
258 be invoked on the original object to read the attribute's value.
259 C<< $self->$reader >> is an example of "reflection" -- instead of using the
260 name of the method, we're using a variable with the name of the method in it.
261 Perl doesn't mind. Another way to write this would be
262 C<< $self->can($reader)->($self) >>. Yuck. :)
263
264     package main;
265     my $app = MyApp::Website->new(url => "http://google.com", name => "Google");
266     $app->dump;
267
268 And we wrap up the example with a script to show off our newfound magic.
269
270 =head1 CONCLUSION
271
272 Why oh why would you want to go through all of these contortions when you can
273 just print "The site's URL" directly in the C<dump> method? For one, the DRY
274 (Don't Repeat Yourself) principle. If you have it in the C<dump> method, you'll
275 probably also have it in the C<as_form> method, and C<to_file>, and so on. So
276 why not have a method that maps attribute names to labels? That could work, but
277 why not include the label where it belongs, in the attribute's definition?
278 That way you're also less likely to forget to add the label.
279
280 More importantly, this was a very simple example. Your metaclasses aren't
281 limited to just adding new meta-attributes. For example, you could implement
282 a metaclass that expires attributes after a certain amount of time. You
283 might use it as such:
284
285     has site_cache => (
286         metaclass     => 'TimedExpiry',
287         expires_after => { hours => 1 },
288         refresh_with  => sub { get($_->url) },
289         isa           => 'Str',
290         is            => 'ro',
291     );
292
293 The sky's the limit!
294
295 =head1 AUTHOR
296
297 Shawn M Moore E<lt>sartak@gmail.comE<gt>
298
299 =head1 COPYRIGHT AND LICENSE
300
301 Copyright 2006-2008 by Infinity Interactive, Inc.
302
303 L<http://www.iinteractive.com>
304
305 This library is free software; you can redistribute it and/or modify
306 it under the same terms as Perl itself.
307
308 =cut
309