Rename Meta::Recipe3 to Meta::Labeled_AttributeTrait

[gitmo/Moose.git] / lib / Moose / Cookbook / Meta / Recipe5.pod

diff --git a/lib/Moose/Cookbook/Meta/Recipe5.pod b/lib/Moose/Cookbook/Meta/Recipe5.pod
index 032a219..54f5c56 100644 (file)
--- a/lib/Moose/Cookbook/Meta/Recipe5.pod
+++ b/lib/Moose/Cookbook/Meta/Recipe5.pod
@@ -1,9 +1,11 @@
+package Moose::Cookbook::Meta::Recipe5;
 
-=pod
+# ABSTRACT: Adding a "table" attribute as a metaclass trait
+
+__END__
 
-=head1 NAME
 
-Moose::Cookbook::Meta::Recipe5 - The "table" attribute as a metaclass trait
+=pod
 
 =head1 SYNOPSIS
 
@@ -25,44 +27,44 @@ Moose::Cookbook::Meta::Recipe5 - The "table" attribute as a metaclass trait
 
 =head1 DESCRIPTION
 
-This recipe takes the metaclass table attribute and reimplements it as
-a metaclass trait. Traits are just roles that Moose applies to
-something for you. In this case, that "something" is the class's
-metaclass object.
+In this recipe, we'll create a class metaclass trait which has a "table"
+attribute. This trait is for classes associated with a DBMS table, as one
+might do for an ORM.
 
-The advantage of using traits is that it's easy to combine multiple
-traits, whereas combining multiple metaclasses can be tricky (which
-subclasses which?).
+In this example, the table name is just a string, but in a real ORM
+the table might be an object describing the table.
 
-The disadvantage is that it's not easy to combine a trait with some
-sort of sugar (like our notional C<has_table> sugar).
+=head1 THE METACLASS TRAIT
 
-=head2 Using this Metaclass Trait in Practice
-
-Once this trait has been applied to a metaclass, it looks exactly like
-the example we saw in L<Moose::Cookbook::Meta::Recipe4>:
+This really is as simple as the recipe L</SYNOPSIS> shows. The trick is
+getting your classes to use this metaclass, and providing some sort of sugar
+for declaring the table. This is covered in
+L<Moose::Cookbook::Extending::Recipe2>, which shows how to make a module like
+C<Moose.pm> itself, with sugar like C<has_table()>.
 
-  my $table = MyApp::User->meta->table;
-
-=head1 SEE ALSO
+=head2 Using this Metaclass Trait in Practice
 
-L<Moose::Cookbook::Meta::Recipe3> - Labels implemented via attribute
-traits
 
-L<Moose::Cookbook::Meta::Recipe4> - Adding a "table" attribute to the
-metaclass
+Accessing this new C<table> attribute is quite simple. Given a class
+named C<MyApp::User>, we could simply write the following:
 
-=head1 AUTHOR
+  my $table = MyApp::User->meta->table;
 
-Dave Rolsky E<lt>autarch@urth.orgE<gt>
+As long as C<MyApp::User> has arranged to apply the
+C<MyApp::Meta::Class::Trait::HasTable> to its metaclass, this method call just
+works. If we want to be more careful, we can check that the class metaclass
+object has a C<table> method:
 
-=head1 COPYRIGHT AND LICENSE
+  $table = MyApp::User->meta->table
+      if MyApp::User->meta->can('table');
 
-Copyright 2006-2008 by Infinity Interactive, Inc.
+In theory, this is not entirely correct, since the metaclass might be getting
+its C<table> method from a I<different> trait. In practice, you are unlikely
+to encounter this sort of problem.
 
-L<http://www.iinteractive.com>
+=head1 SEE ALSO
 
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
+L<Moose::Cookbook::Meta::Labeled_AttributeTrait> - Labels implemented via
+attribute traits
 
 =pod