Note MooseX::AttributeHelpers deprecation

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

diff --git a/lib/Moose/Cookbook/Extending/Recipe1.pod b/lib/Moose/Cookbook/Extending/Recipe1.pod
index a20a1b7..24dc9da 100644 (file)
--- a/lib/Moose/Cookbook/Extending/Recipe1.pod
+++ b/lib/Moose/Cookbook/Extending/Recipe1.pod
@@ -1,9 +1,11 @@
+package Moose::Cookbook::Extending::Recipe1;
 
-=pod
+# ABSTRACT: Moose extension overview
+
+__END__
 
-=head1 NAME
 
-Moose::Cookbook::Extending::Recipe1 - Moose extension overview
+=pod
 
 =head1 DESCRIPTION
 
@@ -46,6 +48,8 @@ Many of the Moose extensions on CPAN work by providing an attribute
 metaclass extension. For example, the L<MooseX::AttributeHelpers>
 distribution provides a new attribute metaclass that lets you delegate
 behavior to a non-object attribute (a hashref or simple number).
+(MooseX::AttributeHelpers has been deprecated in favour of
+L<Moose::Meta::Attribute::Native>, but can still serve as an example).
 
 A metaclass extension can be packaged as a subclass or a
 role/trait. If you can, we recommend using traits instead of
@@ -110,7 +114,7 @@ this works. These both build on top of the L<MooseX::Types> extension.
 =head1 ROLES VS TRAITS VS SUBCLASSES
 
 It is important to understand that B<roles and traits are the same thing>. A
-trait is simply a role applied to a metaclass. The only thing that may
+trait is simply a role applied to a instance. The only thing that may
 distinguish the two is that a trait can be packaged in a way that lets Moose
 resolve a short name to a class name. In other words, with a trait, the caller
 can refer to it by a short name like "Big", and Moose will resolve it to a
@@ -211,42 +215,35 @@ L<Moose::Util::MetaRole> to apply all of your roles. The advantage of
 using this module is that I<it preserves any subclassing or roles
 already applied to the user's metaclasses>. This means that your
 extension is cooperative I<by default>, and consumers of your
-extension can easily use it with other role-based extensions.
+extension can easily use it with other role-based extensions. Most
+uses of L<Moose::Util::MetaRole> can be handled by L<Moose::Exporter>
+directly; see the L<Moose::Exporter> docs.
 
   package MooseX::Embiggen;
 
   use Moose ();
   use Moose::Exporter;
-  use Moose::Util::MetaRole;
 
   use MooseX::Embiggen::Role::Meta::Class;
   use MooseX::Embiggen::Role::Meta::Attribute;
   use MooseX::Embiggen::Role::Meta::Method::Constructor;
   use MooseX::Embiggen::Role::Object;
 
-  Moose::Exporter->setup_import_methods( also => 'Moose' );
+  my ( $import, $unimport, $init_meta ) = Moose::Exporter->build_import_methods(
+      also => ['Moose'] metaclass_roles =>
+          ['MooseX::Embiggen::Role::Meta::Class'],
+      attribute_metaclass_roles => ['MooseX::Embiggen::Role::Meta::Attribute'],
+      constructor_class_roles =>
+          ['MooseX::Embiggen::Role::Meta::Method::Constructor'],
+      base_class_roles => ['MooseX::Embiggen::Role::Object'],
+      install          => [qw(import unimport)],
+  );
 
   sub init_meta {
-      shift;    # just your package name
+      my $package = shift;
       my %options = @_;
-
       Moose->init_meta(%options);
-
-      my $meta = Moose::Util::MetaRole::apply_metaclass_roles(
-          for_class       => $options{for_class},
-          metaclass_roles => ['MooseX::Embiggen::Role::Meta::Class'],
-          attribute_metaclass_roles =>
-              ['MooseX::Embiggen::Role::Meta::Attribute'],
-          constructor_class_roles =>
-              ['MooseX::Embiggen::Role::Meta::Method::Constructor'],
-      );
-
-      Moose::Util::MetaRole::apply_base_class_roles(
-          for_class => $options{for_class},
-          roles     => ['MooseX::Embiggen::Role::Object'],
-      );
-
-      return $meta;
+      return $package->$init_meta(%options);
   }
 
 As you can see from this example, you can use L<Moose::Util::MetaRole>
@@ -265,15 +262,13 @@ as well as those from other modules:
   use Moose::Exporter;
 
   Moose::Exporter->setup_import_methods(
-      with_caller => ['embiggen'],
-      also        => 'Moose',
+      with_meta => ['embiggen'],
+      also      => 'Moose',
   );
 
-  sub init_meta { ... }
-
   sub embiggen {
-      my $caller = shift;
-      $caller->meta()->embiggen(@_);
+      my $meta = shift;
+      $meta->embiggen(@_);
   }
 
 And then the consumer of your extension can use your C<embiggen> sub:
@@ -310,17 +305,4 @@ If you can write your extension as one or more metaclass and base
 object roles, please consider doing so. Make sure to read the docs for
 L<Moose::Exporter> and L<Moose::Util::MetaRole> as well.
 
-=head1 AUTHOR
-
-Dave Rolsky E<lt>autarch@urth.orgE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 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.
-
 =cut