1Moose::Exporter(3) User Contributed Perl Documentation Moose::Exporter(3)
2
6 Moose::Exporter - make an import() and unimport() just like Moose.pm
7
9 package MyApp::Moose;
10 use Moose ();
12 use Moose::Exporter;
13 Moose::Exporter->setup_import_methods(
15 with_meta => [ 'has_rw', 'sugar2' ],
16 as_is => [ 'sugar3', \&Some::Random::thing ],
17 also => 'Moose',
18 );
19 sub has_rw {
21 my ( $meta, $name, %options ) = @_;
22 $meta->add_attribute(
23 $name,
24 is => 'rw',
25 %options,
26 );
27 }
28 # then later ...
30 package MyApp::User;
31 use MyApp::Moose;
33 has 'name';
35 has_rw 'size';
36 thing;
37 no MyApp::Moose;
39
41 This module encapsulates the exporting of sugar functions in a
42 "Moose.pm"-like manner. It does this by building custom "import",
43 "unimport", and "init_meta" methods for your module, based on a spec
44 you provide.
45 It also lets you "stack" Moose-alike modules so you can export Moose's
47 sugar as well as your own, along with sugar from any random "MooseX"
48 module, as long as they all use "Moose::Exporter". This feature exists
49 to let you bundle a set of MooseX modules into a policy module that
50 developers can use directly instead of using Moose itself.
51 To simplify writing exporter modules, "Moose::Exporter" also imports
53 "strict" and "warnings" into your exporter module, as well as into
54 modules that use it.
55
57 This module provides two public methods:
58 Moose::Exporter->setup_import_methods(...)
60 When you call this method, "Moose::Exporter" builds custom
61 "import", "unimport", and "init_meta" methods for your module. The
62 "import" method will export the functions you specify, and can also
63 re-export functions exported by some other module (like
64 "Moose.pm").
65 The "unimport" method cleans the caller's namespace of all the
67 exported functions. This includes any functions you re-export from
68 other packages. However, if the consumer of your package also
69 imports those functions from the original package, they will not be
70 cleaned.
71 If you pass any parameters for Moose::Util::MetaRole, this method
73 will generate an "init_meta" for you as well (see below for
74 details). This "init_meta" will call
75 "Moose::Util::MetaRole::apply_metaroles" and
76 "Moose::Util::MetaRole::apply_base_class_roles" as needed.
77 Note that if any of these methods already exist, they will not be
79 overridden, you will have to use "build_import_methods" to get the
80 coderef that would be installed.
81 This method accepts the following parameters:
83 · with_meta => [ ... ]
85 This list of function names only will be wrapped and then
87 exported. The wrapper will pass the metaclass object for
88 the caller as its first argument.
89 Many sugar functions will need to use this metaclass object
91 to do something to the calling package.
92 · as_is => [ ... ]
94 This list of function names or sub references will be
96 exported as-is. You can identify a subroutine by reference,
97 which is handy to re-export some other module's functions
98 directly by reference ("\&Some::Package::function").
99 If you do export some other package's function, this
101 function will never be removed by the "unimport" method.
102 The reason for this is we cannot know if the caller also
103 explicitly imported the sub themselves, and therefore wants
104 to keep it.
105 · also => $name or \@names
107 This is a list of modules which contain functions that the
109 caller wants to export. These modules must also use
110 "Moose::Exporter". The most common use case will be to
111 export the functions from "Moose.pm". Functions specified
112 by "with_meta" or "as_is" take precedence over functions
113 exported by modules specified by "also", so that a module
114 can selectively override functions exported by another
115 module.
116 "Moose::Exporter" also makes sure all these functions get
118 removed when "unimport" is called.
119 You can also provide parameters for
121 "Moose::Util::MetaRole::apply_metaroles" and
122 "Moose::Util::MetaRole::base_class_roles". Specifically, valid
123 parameters are "class_metaroles", "role_metaroles", and
124 "base_class_roles".
125 Moose::Exporter->build_import_methods(...)
127 Returns two or three code refs, one for "import", one for
128 "unimport", and optionally one for "init_meta", if the appropriate
129 options are passed in.
130 Accepts the additional "install" option, which accepts an arrayref
132 of method names to install into your exporting package. The valid
133 options are "import", "unimport", and "init_meta". Calling
134 "setup_import_methods" is equivalent to calling
135 "build_import_methods" with "install => [qw(import unimport
136 init_meta)]" except that it doesn't also return the methods.
137 Used by "setup_import_methods".
139
141 If you want to set an alternative base object class or metaclass class,
142 see above for details on how this module can call Moose::Util::MetaRole
143 for you.
144 If you want to do something that is not supported by this module,
146 simply define an "init_meta" method in your class. The "import" method
147 that "Moose::Exporter" generates for you will call this method (if it
148 exists). It will always pass the caller to this method via the
149 "for_class" parameter.
150 Most of the time, your "init_meta" method will probably just call
152 "Moose->init_meta" to do the real work:
153 sub init_meta {
155 shift; # our class name
156 return Moose->init_meta( @_, metaclass => 'My::Metaclass' );
157 }
158 Keep in mind that "build_import_methods" will return an "init_meta"
160 method for you, which you can also call from within your custom
161 "init_meta":
162 my ( $import, $unimport, $init_meta ) =
164 Moose::Exporter->build_import_methods( ... );
165 sub import {
167 my $class = shift;
168 ...
170 $class->$import(...);
172 ...
174 }
175 sub unimport { goto &$unimport }
177 sub init_meta {
179 my $class = shift;
180 ...
182 $class->$init_meta(...);
184 ...
186 }
187
189 The "import" method generated by "Moose::Exporter" will allow the user
190 of your module to specify metaclass traits in a "-traits" parameter
191 passed as part of the import:
192 use Moose -traits => 'My::Meta::Trait';
194 use Moose -traits => [ 'My::Meta::Trait', 'My::Other::Trait' ];
196 These traits will be applied to the caller's metaclass instance.
198 Providing traits for an exporting class that does not create a
199 metaclass for the caller is an error.
200
202 See "BUGS" in Moose for details on reporting bugs.
203
205 Dave Rolsky <autarch@urth.org>
206 This is largely a reworking of code in Moose.pm originally written by
208 Stevan Little and others.
209
211 Copyright 2009 by Infinity Interactive, Inc.
212 <http://www.iinteractive.com>
214 This library is free software; you can redistribute it and/or modify it
216 under the same terms as Perl itself.
217perl v5.12.2 2010-08-28 Moose::Exporter(3)