Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Moose::Exporter.3pm

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Moose::Exporter 3"
.TH Moose::Exporter 3 "2009-11-19" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Moose::Exporter \- make an import() and unimport() just like Moose.pm
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package MyApp::Moose;
.Ve
.PP
.Vb 2
\&  use Moose ();
\&  use Moose::Exporter;
.Ve
.PP
.Vb 5
\&  Moose::Exporter\->setup_import_methods(
\&      with_meta => [ 'has_rw', 'sugar2' ],
\&      as_is     => [ 'sugar3', \e&Some::Random::thing ],
\&      also      => 'Moose',
\&  );
.Ve
.PP
.Vb 8
\&  sub has_rw {
\&      my ( $meta, $name, %options ) = @_;
\&      $meta\->add_attribute(
\&          $name,
\&          is => 'rw',
\&          %options,
\&      );
\&  }
.Ve
.PP
.Vb 2
\&  # then later ...
\&  package MyApp::User;
.Ve
.PP
.Vb 1
\&  use MyApp::Moose;
.Ve
.PP
.Vb 3
\&  has 'name';
\&  has_rw 'size';
\&  thing;
.Ve
.PP
.Vb 1
\&  no MyApp::Moose;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module encapsulates the exporting of sugar functions in a
\&\f(CW\*(C`Moose.pm\*(C'\fR\-like manner. It does this by building custom \f(CW\*(C`import\*(C'\fR,
\&\f(CW\*(C`unimport\*(C'\fR, and \f(CW\*(C`init_meta\*(C'\fR methods for your module, based on a spec you
provide.
.PP
It also lets you \*(L"stack\*(R" Moose-alike modules so you can export Moose's sugar
as well as your own, along with sugar from any random \f(CW\*(C`MooseX\*(C'\fR module, as
long as they all use \f(CW\*(C`Moose::Exporter\*(C'\fR. 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.
.PP
To simplify writing exporter modules, \f(CW\*(C`Moose::Exporter\*(C'\fR also imports
\&\f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR into your exporter module, as well as into
modules that use it.
.SH "METHODS"
.IX Header "METHODS"
This module provides two public methods:
.IP "\fBMoose::Exporter\->setup_import_methods(...)\fR" 4
.IX Item "Moose::Exporter->setup_import_methods(...)"
When you call this method, \f(CW\*(C`Moose::Exporter\*(C'\fR builds custom \f(CW\*(C`import\*(C'\fR,
\&\f(CW\*(C`unimport\*(C'\fR, and \f(CW\*(C`init_meta\*(C'\fR methods for your module. The \f(CW\*(C`import\*(C'\fR method
will export the functions you specify, and can also re-export functions
exported by some other module (like \f(CW\*(C`Moose.pm\*(C'\fR).
.Sp
The \f(CW\*(C`unimport\*(C'\fR method cleans the caller's namespace of all the exported
functions.
.Sp
If you pass any parameters for Moose::Util::MetaRole, this method will
generate an \f(CW\*(C`init_meta\*(C'\fR for you as well (see below for details). This
\&\f(CW\*(C`init_meta\*(C'\fR will call \f(CW\*(C`Moose::Util::MetaRole::apply_metaclass_roles\*(C'\fR and
\&\f(CW\*(C`Moose::Util::MetaRole::apply_base_class_roles\*(C'\fR as needed.
.Sp
Note that if any of these methods already exist, they will not be
overridden, you will have to use \f(CW\*(C`build_import_methods\*(C'\fR to get the
coderef that would be installed.
.Sp
This method accepts the following parameters:
.RS 4
.IP "* with_meta => [ ... ]" 8
.IX Item "with_meta => [ ... ]"
This list of function \fInames only\fR will be wrapped and then exported. The
wrapper will pass the metaclass object for the caller as its first argument.
.Sp
Many sugar functions will need to use this metaclass object to do something to
the calling package.
.IP "* as_is => [ ... ]" 8
.IX Item "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 (\f(CW\*(C`\e&Some::Package::function\*(C'\fR).
.Sp
If you do export some other package's function, this function will never be
removed by the \f(CW\*(C`unimport\*(C'\fR method. The reason for this is we cannot know if
the caller \fIalso\fR explicitly imported the sub themselves, and therefore wants
to keep it.
.ie n .IP "* also => $name or \e@names" 8
.el .IP "* also => \f(CW$name\fR or \e@names" 8
.IX Item "also => $name or @names"
This is a list of modules which contain functions that the caller
wants to export. These modules must also use \f(CW\*(C`Moose::Exporter\*(C'\fR. The
most common use case will be to export the functions from \f(CW\*(C`Moose.pm\*(C'\fR.
Functions specified by \f(CW\*(C`with_meta\*(C'\fR or \f(CW\*(C`as_is\*(C'\fR take precedence over
functions exported by modules specified by \f(CW\*(C`also\*(C'\fR, so that a module
can selectively override functions exported by another module.
.Sp
\&\f(CW\*(C`Moose::Exporter\*(C'\fR also makes sure all these functions get removed
when \f(CW\*(C`unimport\*(C'\fR is called.
.RE
.RS 4
.Sp
Any of the \f(CW*_roles\fR options for
\&\f(CW\*(C`Moose::Util::MetaRole::apply_metaclass_roles\*(C'\fR and
\&\f(CW\*(C`Moose::Util::MetaRole::base_class_roles\*(C'\fR are also acceptable.
.RE
.IP "\fBMoose::Exporter\->build_import_methods(...)\fR" 4
.IX Item "Moose::Exporter->build_import_methods(...)"
Returns two or three code refs, one for \f(CW\*(C`import\*(C'\fR, one for
\&\f(CW\*(C`unimport\*(C'\fR, and optionally one for \f(CW\*(C`init_meta\*(C'\fR, if the appropriate
options are passed in.
.Sp
Accepts the additional \f(CW\*(C`install\*(C'\fR option, which accepts an arrayref of method
names to install into your exporting package. The valid options are \f(CW\*(C`import\*(C'\fR,
\&\f(CW\*(C`unimport\*(C'\fR, and \f(CW\*(C`init_meta\*(C'\fR. Calling \f(CW\*(C`setup_import_methods\*(C'\fR is equivalent
to calling \f(CW\*(C`build_import_methods\*(C'\fR with \f(CW\*(C`install => [qw(import unimport
init_meta)]\*(C'\fR except that it doesn't also return the methods.
.Sp
Used by \f(CW\*(C`setup_import_methods\*(C'\fR.
.SH "IMPORTING AND init_meta"
.IX Header "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.
.PP
If you want to do something that is not supported by this module, simply
define an \f(CW\*(C`init_meta\*(C'\fR method in your class. The \f(CW\*(C`import\*(C'\fR method that
\&\f(CW\*(C`Moose::Exporter\*(C'\fR generates for you will call this method (if it exists). It
will always pass the caller to this method via the \f(CW\*(C`for_class\*(C'\fR parameter.
.PP
Most of the time, your \f(CW\*(C`init_meta\*(C'\fR method will probably just call \f(CW\*(C`Moose\->init_meta\*(C'\fR to do the real work:
.PP
.Vb 4
\&  sub init_meta {
\&      shift; # our class name
\&      return Moose\->init_meta( @_, metaclass => 'My::Metaclass' );
\&  }
.Ve
.PP
Keep in mind that \f(CW\*(C`build_import_methods\*(C'\fR will return an \f(CW\*(C`init_meta\*(C'\fR
method for you, which you can also call from within your custom
\&\f(CW\*(C`init_meta\*(C'\fR:
.PP
.Vb 2
\&  my ( $import, $unimport, $init_meta ) =
\&      Moose::Exporter\->build_import_methods( ... );
.Ve
.PP
.Vb 2
\&  sub import {
\&     my $class = shift;
.Ve
.PP
.Vb 1
\&     ...
.Ve
.PP
.Vb 1
\&     $class\->$import(...);
.Ve
.PP
.Vb 2
\&     ...
\&  }
.Ve
.PP
.Vb 1
\&  sub unimport { goto &$unimport }
.Ve
.PP
.Vb 2
\&  sub init_meta {
\&     my $class = shift;
.Ve
.PP
.Vb 1
\&     ...
.Ve
.PP
.Vb 1
\&     $class\->$init_meta(...);
.Ve
.PP
.Vb 2
\&     ...
\&  }
.Ve
.SH "METACLASS TRAITS"
.IX Header "METACLASS TRAITS"
The \f(CW\*(C`import\*(C'\fR method generated by \f(CW\*(C`Moose::Exporter\*(C'\fR will allow the
user of your module to specify metaclass traits in a \f(CW\*(C`\-traits\*(C'\fR
parameter passed as part of the import:
.PP
.Vb 1
\&  use Moose \-traits => 'My::Meta::Trait';
.Ve
.PP
.Vb 1
\&  use Moose \-traits => [ 'My::Meta::Trait', 'My::Other::Trait' ];
.Ve
.PP
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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.PP
This is largely a reworking of code in Moose.pm originally written by
Stevan Little and others.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2009 by Infinity Interactive, Inc.
.PP
<http://www.iinteractive.com>
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.