lib/Moose/Cookbook/Extending/Recipe2.pod

   1
   2 =pod
   3
   4 =begin testing-SETUP
   5
   6 use Test::Requires {
   7     'Test::Output' => '0',
   8 };
   9
  10 =end testing-SETUP
  11
  12 =head1 NAME
  13
  14 Moose::Cookbook::Extending::Recipe2 - Providing a role for the base object class
  15
  16 =head1 SYNOPSIS
  17
  18   package MooseX::Debugging;
  19
  20   use Moose::Exporter;
  21
  22   Moose::Exporter->setup_import_methods(
  23       base_class_roles => ['MooseX::Debugging::Role::Object'],
  24   );
  25
  26   package MooseX::Debugging::Role::Object;
  27
  28   use Moose::Role;
  29
  30   after 'BUILDALL' => sub {
  31       my $self = shift;
  32
  33       warn "Made a new " . ( ref $self ) . " object\n";
  34   };
  35
  36 =head1 DESCRIPTION
  37
  38 In this example, we provide a role for the base object class that adds
  39 some simple debugging output. Every time an object is created, it
  40 spits out a warning saying what type of object it was.
  41
  42 Obviously, a real debugging role would do something more interesting,
  43 but this recipe is all about how we apply that role.
  44
  45 In this case, with the combination of L<Moose::Exporter> and
  46 L<Moose::Util::MetaRole>, we ensure that when a module does C<S<use
  47 MooseX::Debugging>>, it automatically gets the debugging role applied
  48 to its base object class.
  49
  50 There are a few pieces of code worth looking at more closely.
  51
  52   Moose::Exporter->setup_import_methods(
  53       base_class_roles => ['MooseX::Debugging::Role::Object'],
  54   );
  55
  56 This creates an C<import> method in the C<MooseX::Debugging> package. Since we
  57 are not actually exporting anything, we do not pass C<setup_import_methods>
  58 any parameters related to exports, but we need to have an C<import> method to
  59 ensure that our C<init_meta> method is called. The C<init_meta> is created by
  60 C<setup_import_methods> for us, since we passed the C<base_class_roles>
  61 parameter. The generated C<init_meta> will in turn call
  62 L<Moose::Util::MetaRole::apply_base_class_roles|Moose::Util::MetaRole/apply_base_class_roles>.
  63
  64 =head1 AUTHOR
  65
  66 Dave Rolsky E<lt>autarch@urth.orgE<gt>
  67
  68 =head1 COPYRIGHT AND LICENSE
  69
  70 Copyright 2009-2010 by Infinity Interactive, Inc.
  71
  72 L<http://www.iinteractive.com>
  73
  74 This library is free software; you can redistribute it and/or modify
  75 it under the same terms as Perl itself.
  76
  77 =begin testing
  78
  79 {
  80     package Debugged;
  81
  82     use Moose;
  83     MooseX::Debugging->import;
  84 }
  85
  86 stderr_is(
  87     sub { Debugged->new },
  88     "Made a new Debugged object\n",
  89     'got expected output from debugging role'
  90 );
  91
  92 =end testing
  93
  94 =cut