lib/Moose/Cookbook/Meta/Table_MetaclassTrait.pod

   1 package Moose::Cookbook::Meta::Table_MetaclassTrait;
   2
   3 # ABSTRACT: Adding a "table" attribute as a metaclass trait
   4
   5 __END__
   6
   7
   8 =pod
   9
  10 =begin testing-SETUP
  11
  12 BEGIN {
  13   package MyApp::Meta::Class::Trait::HasTable;
  14   use Moose::Role;
  15
  16   has table => (
  17       is  => 'rw',
  18       isa => 'Str',
  19   );
  20 }
  21
  22 =end testing-SETUP
  23
  24 =head1 SYNOPSIS
  25
  26   # in lib/MyApp/Meta/Class/Trait/HasTable.pm
  27   package MyApp::Meta::Class::Trait::HasTable;
  28   use Moose::Role;
  29
  30   has table => (
  31       is  => 'rw',
  32       isa => 'Str',
  33   );
  34
  35   package Moose::Meta::Class::Custom::Trait::HasTable;
  36   sub register_implementation { 'MyApp::Meta::Class::Trait::HasTable' }
  37
  38   # in lib/MyApp/User.pm
  39   package MyApp::User;
  40   use Moose -traits => 'HasTable';
  41
  42   __PACKAGE__->meta->table('User');
  43
  44 =head1 DESCRIPTION
  45
  46 In this recipe, we'll create a class metaclass trait which has a "table"
  47 attribute. This trait is for classes associated with a DBMS table, as one
  48 might do for an ORM.
  49
  50 In this example, the table name is just a string, but in a real ORM
  51 the table might be an object describing the table.
  52
  53 =head1 THE METACLASS TRAIT
  54
  55 This really is as simple as the recipe L</SYNOPSIS> shows. The trick is
  56 getting your classes to use this metaclass, and providing some sort of sugar
  57 for declaring the table. This is covered in
  58 L<Moose::Cookbook::Extending::Debugging_BaseClassRole>, which shows how to
  59 make a module like C<Moose.pm> itself, with sugar like C<has_table()>.
  60
  61 =head2 Using this Metaclass Trait in Practice
  62
  63 Accessing this new C<table> attribute is quite simple. Given a class
  64 named C<MyApp::User>, we could simply write the following:
  65
  66   my $table = MyApp::User->meta->table;
  67
  68 As long as C<MyApp::User> has arranged to apply the
  69 C<MyApp::Meta::Class::Trait::HasTable> to its metaclass, this method call just
  70 works. If we want to be more careful, we can check that the class metaclass
  71 object has a C<table> method:
  72
  73   $table = MyApp::User->meta->table
  74       if MyApp::User->meta->can('table');
  75
  76 In theory, this is not entirely correct, since the metaclass might be getting
  77 its C<table> method from a I<different> trait. In practice, you are unlikely
  78 to encounter this sort of problem.
  79
  80 =head1 RECIPE CAVEAT
  81
  82 This recipe doesn't work when you paste it all into a single file. This is
  83 because the C<< use Moose -traits => 'HasTable'; >> line ends up being
  84 executed before the C<table> attribute is defined.
  85
  86 When the two packages are separate files, this just works.
  87
  88 =head1 SEE ALSO
  89
  90 L<Moose::Cookbook::Meta::Labeled_AttributeTrait> - Labels implemented via
  91 attribute traits
  92
  93 =pod
  94
  95 =begin testing
  96
  97 can_ok( MyApp::User->meta, 'table' );
  98 is( MyApp::User->meta->table, 'User', 'My::User table is User' );
  99
 100 =end testing