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
  26   has url => (
  27       metaclass => 'Labeled',
  28       is        => 'rw',
  29       isa       => 'Str',
  30       label     => "The site's URL",
  31   );
  32
  33   has name => (
  34       is  => 'rw',
  35       isa => 'Str',
  36   );
  37
  38   sub dump {
  39       my $self = shift;
  40
  41       my $meta = $self->meta;
  42
  43       my $dump = '';
  44
  45       for my $attribute ( map { $meta->get_attribute($_) }
  46           sort $meta->get_attribute_list ) {
  47
  48           if (   $attribute->isa('MyApp::Meta::Attribute::Labeled')
  49               && $attribute->has_label ) {
  50               $dump .= $attribute->label;
  51           }
  52           else {
  53               $dump .= $attribute->name;
  54           }
  55
  56           my $reader = $attribute->get_read_method;
  57           $dump .= ": " . $self->$reader . "\n";
  58       }
  59
  60       return $dump;
  61   }
  62
  63   package main;
  64
  65   my $app = MyApp::Website->new( url => "http://google.com", name => "Google" );
  66
  67 =head1 SUMMARY
  68
  69 In this recipe, we begin to delve into the wonder of meta-programming.
  70 Some readers may scoff and claim that this is the arena of only the
  71 most twisted Moose developers. Absolutely not! Any sufficiently
  72 twisted developer can benefit greatly from going more meta.
  73
  74 Our goal is to allow each attribute to have a human-readable "label"
  75 attached to it. Such labels would be used when showing data to an end
  76 user. In this recipe we label the C<url> attribute with "The site's
  77 URL" and create a simple method showing how to use that label.
  78
  79 The proper, modern way to extend attributes (using a role instead of a
  80 subclass) is described in L<Moose::Cookbook::Meta::Recipe3>, but that recipe
  81 assumes you've read and at least tried to understand this one.
  82
  83 =head1 META-ATTRIBUTE OBJECTS
  84
  85 All the attributes of a Moose-based object are actually objects
  86 themselves.  These objects have methods and attributes. Let's look at
  87 a concrete example.
  88
  89   has 'x' => ( isa => 'Int', is => 'ro' );
  90   has 'y' => ( isa => 'Int', is => 'rw' );
  91
  92 Internally, the metaclass for C<Point> has two
  93 L<Moose::Meta::Attribute>. There are several methods for getting
  94 meta-attributes out of a metaclass, one of which is
  95 C<get_attribute_list>. This method is called on the metaclass object.
  96
  97 The C<get_attribute_list> method returns a list of attribute names. You can
  98 then use C<get_attribute> to get the L<Moose::Meta::Attribute> object itself.
  99
 100 Once you have this meta-attribute object, you can call methods on it like this:
 101
 102   print $point->meta->get_attribute('x')->type_constraint;
 103      => Int
 104
 105 To add a label to our attributes there are two steps. First, we need a
 106 new attribute metaclass that can store a label for an
 107 attribute. Second, we need to create attributes that use that
 108 attribute metaclass.
 109
 110 =head1 RECIPE REVIEW
 111
 112 We start by creating a new attribute metaclass.
 113
 114   package MyApp::Meta::Attribute::Labeled;
 115   use Moose;
 116   extends 'Moose::Meta::Attribute';
 117
 118 We can subclass a Moose metaclass in the same way that we subclass
 119 anything else.
 120
 121   has label => (
 122       is        => 'rw',
 123       isa       => 'Str',
 124       predicate => 'has_label',
 125   );
 126
 127 Again, this is standard Moose code.
 128
 129 Then we need to register our metaclass with Moose:
 130
 131   package Moose::Meta::Attribute::Custom::Labeled;
 132   sub register_implementation { 'MyApp::Meta::Attribute::Labeled' }
 133
 134 This is a bit of magic that lets us use a short name, "Labeled", when
 135 referring to our new metaclass.
 136
 137 That was the whole attribute metaclass.
 138
 139 Now we start using it.
 140
 141   package MyApp::Website;
 142   use Moose;
 143   use MyApp::Meta::Attribute::Labeled;
 144
 145 We have to load the metaclass to use it, just like any Perl class.
 146
 147 Finally, we use it for an attribute:
 148
 149   has url => (
 150       metaclass => 'Labeled',
 151       is        => 'rw',
 152       isa       => 'Str',
 153       label     => "The site's URL",
 154   );
 155
 156 This looks like a normal attribute declaration, except for two things,
 157 the C<metaclass> and C<label> parameters. The C<metaclass> parameter
 158 tells Moose we want to use a custom metaclass for this (one)
 159 attribute. The C<label> parameter will be stored in the meta-attribute
 160 object.
 161
 162 The reason that we can pass the name C<Labeled>, instead of
 163 C<MyApp::Meta::Attribute::Labeled>, is because of the
 164 C<register_implementation> code we touched on previously.
 165
 166 When you pass a metaclass to C<has>, it will take the name you provide
 167 and prefix it with C<Moose::Meta::Attribute::Custom::>. Then it calls
 168 C<register_implementation> in the package. In this case, that means
 169 Moose ends up calling
 170 C<Moose::Meta::Attribute::Custom::Labeled::register_implementation>.
 171
 172 If this function exists, it should return the I<real> metaclass
 173 package name. This is exactly what our code does, returning
 174 C<MyApp::Meta::Attribute::Labeled>. This is a little convoluted, and
 175 if you don't like it, you can always use the fully-qualified name.
 176
 177 We can access this meta-attribute and its label like this:
 178
 179   $website->meta->get_attribute('url')->label()
 180
 181   MyApp::Website->meta->get_attribute('url')->label()
 182
 183 We also have a regular attribute, C<name>:
 184
 185   has name => (
 186       is  => 'rw',
 187       isa => 'Str',
 188   );
 189
 190 This is a regular Moose attribute, because we have not specified a new
 191 metaclass.
 192
 193 Finally, we have a C<dump> method, which creates a human-readable
 194 representation of a C<MyApp::Website> object. It will use an
 195 attribute's label if it has one.
 196
 197   sub dump {
 198       my $self = shift;
 199
 200       my $meta = $self->meta;
 201
 202       my $dump = '';
 203
 204       for my $attribute ( map { $meta->get_attribute($_) }
 205           sort $meta->get_attribute_list ) {
 206
 207           if (   $attribute->isa('MyApp::Meta::Attribute::Labeled')
 208               && $attribute->has_label ) {
 209               $dump .= $attribute->label;
 210           }
 211
 212 This is a bit of defensive code. We cannot depend on every
 213 meta-attribute having a label. Even if we define one for every
 214 attribute in our class, a subclass may neglect to do so. Or a
 215 superclass could add an attribute without a label.
 216
 217 We also check that the attribute has a label using the predicate we
 218 defined. We could instead make the label C<required>. If we have a
 219 label, we use it, otherwise we use the attribute name:
 220
 221           else {
 222               $dump .= $attribute->name;
 223           }
 224
 225           my $reader = $attribute->get_read_method;
 226           $dump .= ": " . $self->$reader . "\n";
 227       }
 228
 229       return $dump;
 230   }
 231
 232 The C<get_read_method> is part of the L<Moose::Meta::Attribute>
 233 API. It returns the name of a method that can read the attribute's
 234 value, I<when called on the real object> (don't call this on the
 235 meta-attribute).
 236
 237 =head1 CONCLUSION
 238
 239 You might wonder why you'd bother with all this. You could just
 240 hardcode "The Site's URL" in the C<dump> method. But we want to avoid
 241 repetition. If you need the label once, you may need it elsewhere,
 242 maybe in the C<as_form> method you write next.
 243
 244 Associating a label with an attribute just makes sense! The label is a
 245 piece of information I<about> the attribute.
 246
 247 It's also important to realize that this was a trivial example. You
 248 can make much more powerful metaclasses that I<do> things, as opposed
 249 to just storing some more information. For example, you could
 250 implement a metaclass that expires attributes after a certain amount
 251 of time:
 252
 253    has site_cache => (
 254        metaclass     => 'TimedExpiry',
 255        expires_after => { hours => 1 },
 256        refresh_with  => sub { get( $_[0]->url ) },
 257        isa           => 'Str',
 258        is            => 'ro',
 259    );
 260
 261 The sky's the limit!
 262
 263 =head1 AUTHOR
 264
 265 Shawn M Moore E<lt>sartak@gmail.comE<gt>
 266
 267 Dave Rolsky E<lt>autarch@urth.org<gt>
 268
 269 =head1 COPYRIGHT AND LICENSE
 270
 271 Copyright 2006-2010 by Infinity Interactive, Inc.
 272
 273 L<http://www.iinteractive.com>
 274
 275 This library is free software; you can redistribute it and/or modify
 276 it under the same terms as Perl itself.
 277
 278 =begin testing
 279
 280 my $app = MyApp::Website->new( url => "http://google.com", name => "Google" );
 281 is(
 282     $app->dump, q{name: Google
 283 The site's URL: http://google.com
 284 }, '... got the expected dump value'
 285 );
 286
 287 =end testing
 288
 289 =cut
 290