phpman > perldoc > Moose::Exporter(3pm)

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

VERSION
    version 2.2200

SYNOPSIS
      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;

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::apply_base_class_roles. Specifically, valid parameters are
    "class_metaroles", "role_metaroles", and "base_class_roles".

  Moose::Exporter->build_import_methods(...)
    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 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' );
      }

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.

AUTHORS
    *   Stevan Little <stevan AT cpan.org>

    *   Dave Rolsky <autarch AT urth.org>

    *   Jesse Luehrs <doy AT cpan.org>

    *   Shawn M Moore <sartak AT cpan.org>

    *   יובל קוג'מן (Yuval Kogman) <nothingmuch AT woobling.org>

    *   Karen Etheridge <ether AT cpan.org>

    *   Florian Ragwitz <rafl AT debian.org>

    *   Hans Dieter Pearcey <hdp AT cpan.org>

    *   Chris Prather <chris AT prather.org>

    *   Matt S Trout <mstrout AT cpan.org>

COPYRIGHT AND LICENSE
    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.