From: Dave Rolsky <autarch@urth.org>
Date: Mon, 7 Sep 2009 15:56:38 +0000 (-0500)
Subject: Revise docs for new init_meta generation
X-Git-Tag: 0.89_02~33^2~3
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=37e4fe9594de1209d5836eaee6eaacf995172066;p=gitmo%2FMoose.git

Revise docs for new init_meta generation
---

diff --git a/lib/Moose/Exporter.pm b/lib/Moose/Exporter.pm
index 8a6905d..faebc2c 100644
--- a/lib/Moose/Exporter.pm
+++ b/lib/Moose/Exporter.pm
@@ -643,12 +643,14 @@ Moose::Exporter - make an import() and unimport() just like Moose.pm
 
 This module encapsulates the exporting of sugar functions in a
 C<Moose.pm>-like manner. It does this by building custom C<import>,
-C<unimport>, and optionally C<init_meta> methods for your module,
-based on a spec you provide.
+C<unimport>, and C<init_meta> methods for your module, based on a spec you
+provide.
 
-It also lets you "stack" Moose-alike modules so you can export
-Moose's sugar as well as your own, along with sugar from any random
-C<MooseX> module, as long as they all use C<Moose::Exporter>.
+It also lets you "stack" Moose-alike modules so you can export Moose's sugar
+as well as your own, along with sugar from any random C<MooseX> module, as
+long as they all use C<Moose::Exporter>. This feature exists to let you bundle
+a set of MooseX modules into a policy module that developers can use directly
+instead of using Moose itself.
 
 To simplify writing exporter modules, C<Moose::Exporter> also imports
 C<strict> and C<warnings> into your exporter module, as well as into
@@ -663,17 +665,17 @@ This module provides two public methods:
 =item  B<< Moose::Exporter->setup_import_methods(...) >>
 
 When you call this method, C<Moose::Exporter> builds custom C<import>,
-C<unimport>, and C<init_meta> methods for your module. The C<import>
-method will export the functions you specify, and you can also tell it
-to export functions exported by some other module (like C<Moose.pm>).
+C<unimport>, and C<init_meta> methods for your module. The C<import> method
+will export the functions you specify, and can also re-export functions
+exported by some other module (like C<Moose.pm>).
 
-The C<unimport> method cleans the callers namespace of all the
-exported functions.
+The C<unimport> method cleans the caller's namespace of all the exported
+functions.
 
-The C<init_meta> method will be generated if any parameters for
-L<Moose::Util::MetaRole> are passed to C<setup_import_methods> (see
-below). It will handle passing along the required traits to
-C<apply_metaclass_roles> and C<apply_base_class_roles> as needed.
+If you pass any parameters for L<Moose::Util::MetaRole>, this method will
+generate an C<init_meta> for you as well (see below for details). This
+C<init_meta> will call C<Moose::Util::MetaRole::apply_metaclass_roles> and
+C<Moose::Util::MetaRole::apply_base_class_roles> as needed.
 
 Note that if any of these methods already exist, they will not be
 overridden, you will have to use C<build_import_methods> to get the
@@ -685,22 +687,21 @@ This method accepts the following parameters:
 
 =item * with_caller => [ ... ]
 
-This a list of function I<names only> to be exported wrapped and then
-exported. The wrapper will pass the name of the calling package as the
-first argument to the function. Many sugar functions need to know
-their caller so they can get the calling package's metaclass object.
+This list of function I<names only> will be wrapped and then exported. The
+wrapper will pass the name of the calling package as the first argument to the
+function. Many sugar functions need to know their caller so they can get the
+calling package's metaclass object.
 
 =item * as_is => [ ... ]
 
-This a list of function names or sub references to be exported
-as-is. You can identify a subroutine by reference, which is handy to
-re-export some other module's functions directly by reference
-(C<\&Some::Package::function>).
+This list of function names or sub references will be exported as-is. You can
+identify a subroutine by reference, which is handy to re-export some other
+module's functions directly by reference (C<\&Some::Package::function>).
 
-If you do export some other packages function, this function will
-never be removed by the C<unimport> method. The reason for this is we
-cannot know if the caller I<also> explicitly imported the sub
-themselves, and therefore wants to keep it.
+If you do export some other package's function, this function will never be
+removed by the C<unimport> method. The reason for this is we cannot know if
+the caller I<also> explicitly imported the sub themselves, and therefore wants
+to keep it.
 
 =item * also => $name or \@names
 
@@ -717,9 +718,8 @@ when C<unimport> is called.
 =back
 
 Any of the C<*_roles> options for
-C<Moose::Util::MetaRole::apply_metaclass_roles> are also valid here,
-and C<base_class_roles> will be passed along to the C<roles> parameter
-of C<Moose::Util::MetaRole::apply_base_class_roles>.
+C<Moose::Util::MetaRole::apply_metaclass_roles> and
+C<Moose::Util::MetaRole::base_class_roles> are also acceptable.
 
 =item B<< Moose::Exporter->build_import_methods(...) >>
 
@@ -727,12 +727,11 @@ Returns two or three code refs, one for C<import>, one for
 C<unimport>, and optionally one for C<init_meta>, if the appropriate
 options are passed in.
 
-Accepts the additional C<install> option, which accepts an arrayref of
-method names to install into your exporter (C<import>, C<unimport>,
-and C<init_meta>). Calling C<setup_import_methods> is equivalent to
-calling C<build_import_methods> with
-C<< install => [qw(import unimport init_meta)] >> (except that it
-doesn't also return the methods).
+Accepts the additional C<install> option, which accepts an arrayref of method
+names to install into your exporting package. The valid options are C<import>,
+C<unimport>, and C<init_meta>. Calling C<setup_import_methods> is equivalent
+to calling C<build_import_methods> with C<< install => [qw(import unimport
+init_meta)] >> except that it doesn't also return the methods.
 
 Used by C<setup_import_methods>.
 
@@ -740,13 +739,14 @@ Used by C<setup_import_methods>.
 
 =head1 IMPORTING AND init_meta
 
-If you want to set an alternative base object class or metaclass
-class, see above for how to pass options to L<Moose::Util::MetaRole>
-through the options to C<setup_import_methods>. If you want to do
-something not supported by this, simply define an C<init_meta> method
-in your class. The C<import> method that C<Moose::Exporter> generates
-for you will call this method (if it exists). It will always pass the
-caller to this method via the C<for_class> parameter.
+If you want to set an alternative base object class or metaclass class, see
+above for details on how this module can call L<Moose::Util::MetaRole> for
+you.
+
+If you want to do something that is not supported by this module, simply
+define an C<init_meta> method in your class. The C<import> method that
+C<Moose::Exporter> generates for you will call this method (if it exists). It
+will always pass the caller to this method via the C<for_class> parameter.
 
 Most of the time, your C<init_meta> method will probably just call C<<
 Moose->init_meta >> to do the real work:
@@ -758,7 +758,32 @@ Moose->init_meta >> to do the real work:
 
 Keep in mind that C<build_import_methods> will return an C<init_meta>
 method for you, which you can also call from within your custom
-C<init_meta>.
+C<init_meta>:
+
+  my ( $import, $unimport, $init_meta ) =
+      Moose::Exporter->build_import_methods( ... );
+
+  sub import {
+     my $class = shift;
+
+     ...
+
+     $class->$import(...);
+
+     ...
+  }
+
+  sub unimport { goto &$unimport }
+
+  sub init_meta {
+     my $class = shift;
+
+     ...
+
+     $class->$init_meta(...);
+
+     ...
+  }
 
 =head1 METACLASS TRAITS