Moose::Exporter - make an import() and unimport() just like Moose.pm
version 2.2201
package MyApp::Moose;
use Moose ();
use Moose::Exporter;
use Some::Random ();
Moose::Exporter->setup_import_methods(
with_meta => [ 'has_rw', 'sugar2' ],
as_is => [ 'sugar3', \&Some::Random::thing, 'Some::Random::other_thing' ],
also => 'Moose',
);
sub has_rw {
my ( $meta, $name, %options ) = @_;
$meta->add_attribute(
$name,
is => 'rw',
%options,
);
}
# then later ...
package MyApp::User;
use MyApp::Moose;
has 'name' => ( is => 'ro' );
has_rw 'size';
thing;
other_thing;
no MyApp::Moose;
This module encapsulates the exporting of sugar functions in a
Moose.pm-like manner. It does this by building custom import and
unimport 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 MooseX module, as
long as they all use 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, Moose::Exporter also imports
strict and warnings into your exporter module, as well as into
modules that use it.
This module provides two public methods:
When you call this method, Moose::Exporter builds custom import and
unimport methods for your module. The import method
will export the functions you specify, and can also re-export functions
exported by some other module (like Moose.pm). If you pass any parameters
for the Moose::Util::MetaRole manpage, the import method will also call
Moose::Util::MetaRole::apply_metaroles and
Moose::Util::MetaRole::apply_base_class_roles as needed, after making
sure the metaclass is initialized.
The unimport method cleans the caller's namespace of all the exported
functions. This includes any functions you re-export from other
packages. However, if the consumer of your package also imports those
functions from the original package, they will not be cleaned.
Note that if any of these methods already exist, they will not be
overridden, you will have to use build_import_methods to get the
coderef that would be installed.
This method accepts the following parameters:
- with_meta => [ ... ]
This list of function names only will be wrapped and then exported. The
wrapper will pass the metaclass object for the caller as its first argument.
Many sugar functions will need to use this metaclass object to do something to
the calling package.
- as_is => [ ... ]
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 (\&Some::Package::function).
If you do export some other package's function, this function will never be
removed by the unimport method. The reason for this is we cannot know if
the caller also explicitly imported the sub themselves, and therefore wants
to keep it.
- trait_aliases => [ ... ]
This is a list of package names which should have shortened aliases exported,
similar to the functionality of aliased. Each element in the list can be
either a package name, in which case the export will be named as the last
namespace component of the package, or an arrayref, whose first element is the
package to alias to, and second element is the alias to export.
- also => $name or \@names
This is a list of modules which contain functions that the caller
wants to export. These modules must also use Moose::Exporter. The
most common use case will be to export the functions from Moose.pm.
Functions specified by with_meta or as_is take precedence over
functions exported by modules specified by also, so that a module
can selectively override functions exported by another module.
Moose::Exporter also makes sure all these functions get removed
when unimport is called.
- meta_lookup => sub { ... }
This is a function which will be called to provide the metaclass
to be operated upon by the exporter. This is an advanced feature
intended for use by package generator modules in the vein of
the MooseX::Role::Parameterized manpage in order to simplify reusing sugar
from other modules that use Moose::Exporter. This function is
used, for example, to select the metaclass to bind to functions
that are exported using the with_meta option.
This function will receive one parameter: the class name into which
the sugar is being exported. The default implementation is:
sub { Class::MOP::class_of(shift) }
Accordingly, this function is expected to return a metaclass.
You can also provide parameters for Moose::Util::MetaRole::apply_metaroles
and Moose::Util::MetaRole::apply_base_class_roles. Specifically, valid parameters
are ``class_metaroles'', ``role_metaroles'', and ``base_class_roles''.
Returns three code refs, one for import, one for unimport and one for
init_meta.
Accepts the additional install option, which accepts an arrayref of method
names to install into your exporting package. The valid options are import
and unimport. Calling setup_import_methods is equivalent
to calling build_import_methods with install => [qw(import unimport)]
except that it doesn't also return the methods.
The import method is built using the Sub::Exporter manpage. This means that it can
take a hashref of the form { into => $package } to specify the package
it operates on.
Used by setup_import_methods.
If you want to set an alternative base object class or metaclass class, see
above for details on how this module can call the Moose::Util::MetaRole manpage for
you.
If you want to do something that is not supported by this module, simply
define an init_meta method in your class. The import method that
Moose::Exporter generates for you will call this method (if it exists). It
will always pass the caller to this method via the for_class parameter.
Most of the time, your init_meta method will probably just call <
Moose-init_meta >> to do the real work:
sub init_meta {
shift; # our class name
return Moose->init_meta( @_, metaclass => 'My::Metaclass' );
}
The import method generated by Moose::Exporter will allow the
user of your module to specify metaclass traits in a -traits
parameter passed as part of the import:
use Moose -traits => 'My::Meta::Trait';
use Moose -traits => [ 'My::Meta::Trait', 'My::Other::Trait' ];
These traits will be applied to the caller's metaclass
instance. Providing traits for an exporting class that does not create
a metaclass for the caller is an error.
See Moose/BUGS for details on reporting bugs.
This software is copyright (c) 2006 by Infinity Interactive, Inc.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
|