1Moose::Exporter(3)    User Contributed Perl Documentation   Moose::Exporter(3)
2
3
4

NAME

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

VERSION

9       version 2.2201
10

SYNOPSIS

12         package MyApp::Moose;
13
14         use Moose ();
15         use Moose::Exporter;
16         use Some::Random ();
17
18         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
24         sub has_rw {
25             my ( $meta, $name, %options ) = @_;
26             $meta->add_attribute(
27                 $name,
28                 is => 'rw',
29                 %options,
30             );
31         }
32
33         # then later ...
34         package MyApp::User;
35
36         use MyApp::Moose;
37
38         has 'name' => ( is => 'ro' );
39         has_rw 'size';
40         thing;
41         other_thing;
42
43         no MyApp::Moose;
44

DESCRIPTION

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
50       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
56       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

METHODS

61       This module provides two public methods:
62
63   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
73       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
78       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
82       This method accepts the following parameters:
83
84       •   with_meta => [ ... ]
85
86           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
90           Many sugar functions will need to use this metaclass object to do
91           something to the calling package.
92
93       •   as_is => [ ... ]
94
95           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
100           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
105       •   trait_aliases => [ ... ]
106
107           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
114       •   also => $name or \@names
115
116           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
124           "Moose::Exporter" also makes sure all these functions get removed
125           when "unimport" is called.
126
127       •   meta_lookup => sub { ... }
128
129           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
137           This function will receive one parameter: the class name into which
138           the sugar is being exported. The default implementation is:
139
140               sub { Class::MOP::class_of(shift) }
141
142           Accordingly, this function is expected to return a metaclass.
143
144       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
150   Moose::Exporter->build_import_methods(...)
151       Returns three code refs, one for "import", one for "unimport" and one
152       for "init_meta".
153
154       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
160       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
164       Used by "setup_import_methods".
165

IMPORTING AND init_meta

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
171       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
177       Most of the time, your "init_meta" method will probably just call
178       "Moose->init_meta" to do the real work:
179
180         sub init_meta {
181             shift; # our class name
182             return Moose->init_meta( @_, metaclass => 'My::Metaclass' );
183         }
184

METACLASS TRAITS

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
190         use Moose -traits => 'My::Meta::Trait';
191
192         use Moose -traits => [ 'My::Meta::Trait', 'My::Other::Trait' ];
193
194       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

BUGS

199       See "BUGS" in Moose for details on reporting bugs.
200

AUTHORS

202       •   Stevan Little <stevan@cpan.org>
203
204       •   Dave Rolsky <autarch@urth.org>
205
206       •   Jesse Luehrs <doy@cpan.org>
207
208       •   Shawn M Moore <sartak@cpan.org>
209
210       •   יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
211
212       •   Karen Etheridge <ether@cpan.org>
213
214       •   Florian Ragwitz <rafl@debian.org>
215
216       •   Hans Dieter Pearcey <hdp@cpan.org>
217
218       •   Chris Prather <chris@prather.org>
219
220       •   Matt S Trout <mstrout@cpan.org>
221
223       This software is copyright (c) 2006 by Infinity Interactive, Inc.
224
225       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.
227
228
229
230perl v5.34.0                      2022-01-21                Moose::Exporter(3)
Impressum