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
=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
=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
=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(...) >>
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>.
=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:
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
projects / gitmo/Moose.git / commitdiff