Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

Moose::Exporter(3)                   User Contributed Perl Documentation                  Moose::Exporter(3)



NAME
       Moose::Exporter - make an import() and unimport() just like Moose.pm

VERSION
       version 2.0205

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", "unimport", and "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 "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", "unimport", and "init_meta"
           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").

           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.

           If you pass any parameters for Moose::Util::MetaRole, this method will generate an "init_meta"
           for you as well (see below for details). This "init_meta" will call
           "Moose::Util::MetaRole::apply_metaroles" and "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 "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.

           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 or three code refs, one for "import", one for "unimport", and optionally one for
           "init_meta", if the appropriate options are passed in.

           Accepts the additional "install" option, which accepts an arrayref of method names to install
           into your exporting package. The valid options are "import", "unimport", and "init_meta". Calling
           "setup_import_methods" is equivalent to calling "build_import_methods" with "install =>
           [qw(import unimport init_meta)]" 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".

IMPORTING AND init_meta
       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' );
         }

       Keep in mind that "build_import_methods" will return an "init_meta" method for you, which you can
       also call from within your custom "init_meta":

         my ( $import, $unimport, $init_meta )
             = Moose::Exporter->build_import_methods(...);

         sub import {
             my $class = shift;

             ...

             # You can either pass an explicit package to import into ...
             $class->$import( { into => scalar(caller) }, ... );

             ...;
         }

         # ... or you can use 'goto' to provide the correct caller info to the
         # generated method
         sub unimport { goto &$unimport }

         sub init_meta {
             my $class = shift;

             ...

             $class->$init_meta(...);

             ...
         }

METACLASS TRAITS
       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
       Stevan Little <stevan@iinteractive.com>

COPYRIGHT AND LICENSE
       This software is copyright (c) 2011 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.



perl v5.12.5                                     2011-09-06                               Moose::Exporter(3)