init_meta documentation

[gitmo/Moose.git] / lib / Moose / Cookbook / Extending / Recipe3.pod

diff --git a/lib/Moose/Cookbook/Extending/Recipe3.pod b/lib/Moose/Cookbook/Extending/Recipe3.pod
index 3abe740..544a86f 100644 (file)
--- a/lib/Moose/Cookbook/Extending/Recipe3.pod
+++ b/lib/Moose/Cookbook/Extending/Recipe3.pod
@@ -1,6 +1,19 @@
 
 =pod
 
+=begin testing-SETUP
+
+BEGIN {
+    eval 'use Test::Warn 0.11;';
+    if ($@) {
+        diag 'Test::Warn 0.11+ is required for this test';
+        ok(1);
+        exit 0;
+    }
+}
+
+=end testing-SETUP
+
 =head1 NAME
 
 Moose::Cookbook::Extending::Recipe3 - Providing an alternate base object class
@@ -24,34 +37,33 @@ Moose::Cookbook::Extending::Recipe3 - Providing an alternate base object class
 
   sub init_meta {
       shift;
-      Moose->init_meta( @_, base_class => 'MyApp::Object' );
+      return Moose->init_meta( @_, base_class => 'MyApp::Base' );
   }
 
 =head1 DESCRIPTION
 
-Often you find that you want to share some behavior between all your
-classes. One way to do that is to make a base class and simply add
-C<S<extends 'MyApp::Base'>> to every class in your
-application. However, that can get tedious. Instead, you can simply
-create your Moose-alike module that sets the base object class to
-C<MyApp::Base> for you.
+A common extension is to provide an alternate base class. One way to
+do that is to make a C<MyApp::base> and add C<S<extends
+'MyApp::Base'>> to every class in your application. That's pretty
+tedious. Instead, you can create a Moose-alike module that sets the
+base object class to C<MyApp::Base> for you.
 
 Then, instead of writing C<S<use Moose>> you can write C<S<use
 MyApp::UseMyBase>>.
 
 In this particular example, our base class issues some debugging
-output every time a new object is created, but you can surely think of
-some more interesting things to do with your own base class.
+output every time a new object is created, but you can think of some
+more interesting things to do with your own base class.
 
-This all works because of the magic of L<Moose::Exporter>. When we
-call C<< Moose::Exporter->setup_import_methods( also => 'Moose' ) >>
-it builds an C<import> and C<unimport> method for you. The C<< also =>
-'Moose' >> bit says that we want to export everything that Moose does.
+This uses the magic of L<Moose::Exporter>. When we call C<<
+Moose::Exporter->setup_import_methods( also => 'Moose' ) >> it builds
+C<import> and C<unimport> methods for you. The C<< also => 'Moose' >>
+bit says that we want to export everything that Moose does.
 
 The C<import> method that gets created will call our C<init_meta>
-method, passing it C<< for_caller => $caller >> as its arguments. The
-C<$caller> is set to the class that actually imported us in the first
-place.
+method, passing it C<< for_caller => $caller >> as its
+arguments. The C<$caller> is set to the class that actually imported
+us in the first place.
 
 See the L<Moose::Exporter> docs for more details on its API.
 
@@ -69,17 +81,48 @@ class.
 
   no MyApp::UseMyBase;
 
+=head1 CONCLUSION
+
+This is an awful lot of magic for a simple base class. You will often
+want to combine a metaclass trait with a base class extension, and
+that's when this technique is useful.
+
 =head1 AUTHOR
 
 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2006-2008 by Infinity Interactive, Inc.
+Copyright 2006-2009 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself.
 
+=begin testing
+
+{
+    package Foo;
+
+    MyApp::UseMyBase->import;
+
+    has( 'size' => ( is => 'rw' ) );
+}
+
+ok( Foo->isa('MyApp::Base'), 'Foo isa MyApp::Base' );
+
+ok( Foo->can('size'), 'Foo has a size method' );
+
+my $foo;
+warning_is(
+    sub { $foo = Foo->new( size => 2 ) },
+    'Making a new Foo',
+    'got expected warning when calling Foo->new'
+);
+
+is( $foo->size(), 2, '$foo->size is 2' );
+
+=end testing
+
 =cut