lib/Moose/Cookbook/Extending/Recipe3.pod

   1 package Moose::Cookbook::Extending::Recipe3;
   2
   3 # ABSTRACT: Providing an alternate base object class
   4
   5 __END__
   6
   7
   8 =pod
   9
  10 =begin testing-SETUP
  11
  12 use Test::Requires {
  13     'Test::Output' => '0',
  14 };
  15
  16 =end testing-SETUP
  17
  18 =head1 SYNOPSIS
  19
  20   package MyApp::Base;
  21   use Moose;
  22
  23   extends 'Moose::Object';
  24
  25   before 'new' => sub { warn "Making a new " . $_[0] };
  26
  27   no Moose;
  28
  29   package MyApp::UseMyBase;
  30   use Moose ();
  31   use Moose::Exporter;
  32
  33   Moose::Exporter->setup_import_methods( also => 'Moose' );
  34
  35   sub init_meta {
  36       shift;
  37       return Moose->init_meta( @_, base_class => 'MyApp::Base' );
  38   }
  39
  40 =head1 DESCRIPTION
  41
  42 A common extension is to provide an alternate base class. One way to
  43 do that is to make a C<MyApp::Base> and add C<S<extends
  44 'MyApp::Base'>> to every class in your application. That's pretty
  45 tedious. Instead, you can create a Moose-alike module that sets the
  46 base object class to C<MyApp::Base> for you.
  47
  48 Then, instead of writing C<S<use Moose>> you can write C<S<use
  49 MyApp::UseMyBase>>.
  50
  51 In this particular example, our base class issues some debugging
  52 output every time a new object is created, but you can think of some
  53 more interesting things to do with your own base class.
  54
  55 This uses the magic of L<Moose::Exporter>. When we call C<<
  56 Moose::Exporter->setup_import_methods( also => 'Moose' ) >> it builds
  57 C<import> and C<unimport> methods for you. The C<< also => 'Moose' >>
  58 bit says that we want to export everything that Moose does.
  59
  60 The C<import> method that gets created will call our C<init_meta>
  61 method, passing it C<< for_caller => $caller >> as its
  62 arguments. The C<$caller> is set to the class that actually imported
  63 us in the first place.
  64
  65 See the L<Moose::Exporter> docs for more details on its API.
  66
  67 =head1 USING MyApp::UseMyBase
  68
  69 To actually use our new base class, we simply use C<MyApp::UseMyBase>
  70 I<instead> of C<Moose>. We get all the Moose sugar plus our new base
  71 class.
  72
  73   package Foo;
  74
  75   use MyApp::UseMyBase;
  76
  77   has 'size' => ( is => 'rw' );
  78
  79   no MyApp::UseMyBase;
  80
  81 =head1 CONCLUSION
  82
  83 This is an awful lot of magic for a simple base class. You will often
  84 want to combine a metaclass trait with a base class extension, and
  85 that's when this technique is useful.
  86
  87 =begin testing
  88
  89 {
  90     package Foo;
  91
  92     MyApp::UseMyBase->import;
  93
  94     has( 'size' => ( is => 'rw' ) );
  95 }
  96
  97 ok( Foo->isa('MyApp::Base'), 'Foo isa MyApp::Base' );
  98
  99 ok( Foo->can('size'), 'Foo has a size method' );
 100
 101 my $foo;
 102 stderr_like(
 103     sub { $foo = Foo->new( size => 2 ) },
 104     qr/^Making a new Foo/,
 105     'got expected warning when calling Foo->new'
 106 );
 107
 108 is( $foo->size(), 2, '$foo->size is 2' );
 109
 110 =end testing
 111
 112 =cut