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 version 2.2014
10
12 package MyApp::Moose;
13 use Moose ();
15 use Moose::Exporter;
16 use Some::Random ();
17 Moose::Exporter->setup_import_methods(
19 with_meta => [ 'has_rw', 'sugar2' ],
20 as_is => [ 'sugar3', \&Some::Random::thing, 'Some::Random::other_thing' ],
21 also => 'Moose',
22 );
23 sub has_rw {
25 my ( $meta, $name, %options ) = @_;
26 $meta->add_attribute(
27 $name,
28 is => 'rw',
29 %options,
30 );
31 }
32 # then later ...
34 package MyApp::User;
35 use MyApp::Moose;
37 has 'name' => ( is => 'ro' );
39 has_rw 'size';
40 thing;
41 other_thing;
42 no MyApp::Moose;
44
46 This module encapsulates the exporting of sugar functions in a
47 "Moose.pm"-like manner. It does this by building custom "import" and
48 "unimport" methods for your module, based on a spec you provide.
49 It also lets you "stack" Moose-alike modules so you can export Moose's
51 sugar as well as your own, along with sugar from any random "MooseX"
52 module, as long as they all use "Moose::Exporter". This feature exists
53 to let you bundle a set of MooseX modules into a policy module that
54 developers can use directly instead of using Moose itself.
55 To simplify writing exporter modules, "Moose::Exporter" also imports
57 "strict" and "warnings" into your exporter module, as well as into
58 modules that use it.
59
61 This module provides two public methods:
62 Moose::Exporter->setup_import_methods(...)
64 When you call this method, "Moose::Exporter" builds custom "import" and
65 "unimport" methods for your module. The "import" method will export the
66 functions you specify, and can also re-export functions exported by
67 some other module (like "Moose.pm"). If you pass any parameters for
68 Moose::Util::MetaRole, the "import" method will also call
69 Moose::Util::MetaRole::apply_metaroles and
70 Moose::Util::MetaRole::apply_base_class_roles as needed, after making
71 sure the metaclass is initialized.
72 The "unimport" method cleans the caller's namespace of all the exported
74 functions. This includes any functions you re-export from other
75 packages. However, if the consumer of your package also imports those
76 functions from the original package, they will not be cleaned.
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 exported.
87 The wrapper will pass the metaclass object for the caller as its
88 first argument.
89 Many sugar functions will need to use this metaclass object to do
91 something to the calling package.
92 • as_is => [ ... ]
94 This list of function names or sub references will be exported as-
96 is. You can identify a subroutine by reference, which is handy to
97 re-export some other module's functions directly by reference
98 ("\&Some::Package::function").
99 If you do export some other package's function, this function will
101 never be removed by the "unimport" method. The reason for this is
102 we cannot know if the caller also explicitly imported the sub
103 themselves, and therefore wants to keep it.
104 • trait_aliases => [ ... ]
106 This is a list of package names which should have shortened aliases
108 exported, similar to the functionality of aliased. Each element in
109 the list can be either a package name, in which case the export
110 will be named as the last namespace component of the package, or an
111 arrayref, whose first element is the package to alias to, and
112 second element is the alias to export.
113 • also => $name or \@names
115 This is a list of modules which contain functions that the caller
117 wants to export. These modules must also use "Moose::Exporter". The
118 most common use case will be to export the functions from
119 "Moose.pm". Functions specified by "with_meta" or "as_is" take
120 precedence over functions exported by modules specified by "also",
121 so that a module can selectively override functions exported by
122 another module.
123 "Moose::Exporter" also makes sure all these functions get removed
125 when "unimport" is called.
126 • meta_lookup => sub { ... }
128 This is a function which will be called to provide the metaclass to
130 be operated upon by the exporter. This is an advanced feature
131 intended for use by package generator modules in the vein of
132 MooseX::Role::Parameterized in order to simplify reusing sugar from
133 other modules that use "Moose::Exporter". This function is used,
134 for example, to select the metaclass to bind to functions that are
135 exported using the "with_meta" option.
136 This function will receive one parameter: the class name into which
138 the sugar is being exported. The default implementation is:
139 sub { Class::MOP::class_of(shift) }
141 Accordingly, this function is expected to return a metaclass.
143 You can also provide parameters for
145 Moose::Util::MetaRole::apply_metaroles and
146 Moose::Util::MetaRole::apply_base_class_roles. Specifically, valid
147 parameters are "class_metaroles", "role_metaroles", and
148 "base_class_roles".
149 Moose::Exporter->build_import_methods(...)
151 Returns three code refs, one for "import", one for "unimport" and one
152 for "init_meta".
153 Accepts the additional "install" option, which accepts an arrayref of
155 method names to install into your exporting package. The valid options
156 are "import" and "unimport". Calling "setup_import_methods" is
157 equivalent to calling "build_import_methods" with "install =>
158 [qw(import unimport)]" except that it doesn't also return the methods.
159 The "import" method is built using Sub::Exporter. This means that it
161 can take a hashref of the form "{ into => $package }" to specify the
162 package it operates on.
163 Used by "setup_import_methods".
165
167 If you want to set an alternative base object class or metaclass class,
168 see above for details on how this module can call Moose::Util::MetaRole
169 for you.
170 If you want to do something that is not supported by this module,
172 simply define an "init_meta" method in your class. The "import" method
173 that "Moose::Exporter" generates for you will call this method (if it
174 exists). It will always pass the caller to this method via the
175 "for_class" parameter.
176 Most of the time, your "init_meta" method will probably just call
178 "Moose->init_meta" to do the real work:
179 sub init_meta {
181 shift; # our class name
182 return Moose->init_meta( @_, metaclass => 'My::Metaclass' );
183 }
184
186 The "import" method generated by "Moose::Exporter" will allow the user
187 of your module to specify metaclass traits in a "-traits" parameter
188 passed as part of the import:
189 use Moose -traits => 'My::Meta::Trait';
191 use Moose -traits => [ 'My::Meta::Trait', 'My::Other::Trait' ];
193 These traits will be applied to the caller's metaclass instance.
195 Providing traits for an exporting class that does not create a
196 metaclass for the caller is an error.
197
199 See "BUGS" in Moose for details on reporting bugs.
200
202 • Stevan Little <stevan@cpan.org>
203 • Dave Rolsky <autarch@urth.org>
205 • Jesse Luehrs <doy@cpan.org>
207 • Shawn M Moore <sartak@cpan.org>
209 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
211 • Karen Etheridge <ether@cpan.org>
213 • Florian Ragwitz <rafl@debian.org>
215 • Hans Dieter Pearcey <hdp@cpan.org>
217 • Chris Prather <chris@prather.org>
219 • Matt S Trout <mstrout@cpan.org>
221
223 This software is copyright (c) 2006 by Infinity Interactive, Inc.
224 This is free software; you can redistribute it and/or modify it under
226 the same terms as the Perl 5 programming language system itself.
227perl v5.32.1 2021-01-27 Moose::Exporter(3)