NAME¶
Moose::Exporter - make an import() and unimport() just like Moose.pm
VERSION¶
version 2.0603
SYNOPSIS¶
package MyApp::Moose;
use Moose ();
use Moose::Exporter;
Moose::Exporter->setup_import_methods(
with_meta => [ 'has_rw', 'sugar2' ],
as_is => [ 'sugar3', \&Some::Random::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';
has_rw 'size';
thing;
no MyApp::Moose;
DESCRIPTION¶
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.
METHODS¶
This module provides two public methods:
- Moose::Exporter->setup_import_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
Moose::Util::MetaRole, 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
MooseX::Role::Parameterized 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::base_class_roles". Specifically, valid
parameters are "class_metaroles", "role_metaroles", and
"base_class_roles".
- Moose::Exporter->build_import_methods(...)
- Returns two code refs, one for "import" and one
for "unimport".
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 Sub::Exporter. 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 Moose::Util::MetaRole 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.
BUGS¶
See "BUGS" in Moose for details on reporting bugs.
AUTHOR¶
Moose is maintained by the Moose Cabal, along with the help of many
contributors. See "CABAL" in Moose and "CONTRIBUTORS" in
Moose for details.
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2012 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.