f5fdb70a9355e16b0adbf2087d2f7398f72e0275
[gitmo/Mouse.git] / lib / Mouse / Exporter.pm
1 package Mouse::Exporter;
2 use strict;
3 use warnings;
4
5 use Carp ();
6
7 my %SPEC;
8
9 my $strict_bits;
10 BEGIN{ $strict_bits = strict::bits(qw(subs refs vars)); }
11
12 my $warnings_extra_bits;
13 BEGIN{ $warnings_extra_bits = warnings::bits(FATAL => 'recursion') }
14
15 # it must be "require", because Mouse::Util depends on Mouse::Exporter,
16 # which depends on Mouse::Util::import()
17 require Mouse::Util;
18
19 sub import{
20     # strict->import;
21     $^H              |= $strict_bits;
22     # warnings->import('all', FATAL => 'recursion');
23     ${^WARNING_BITS} |= $warnings::Bits{all};
24     ${^WARNING_BITS} |= $warnings_extra_bits;
25     return;
26 }
27
28
29 sub setup_import_methods{
30     my($class, %args) = @_;
31
32     my $exporting_package = $args{exporting_package} ||= caller();
33
34     my($import, $unimport) = $class->build_import_methods(%args);
35
36     Mouse::Util::install_subroutines($exporting_package,
37         import   => $import,
38         unimport => $unimport,
39
40         export_to_level => sub {
41             my($package, $level, undef, @args) = @_; # the third argument is redundant
42             $package->import({ into_level => $level + 1 }, @args);
43         },
44         export => sub {
45             my($package, $into, @args) = @_;
46             $package->import({ into => $into }, @args);
47         },
48     );
49     return;
50 }
51
52 sub build_import_methods{
53     my($self, %args) = @_;
54
55     my $exporting_package = $args{exporting_package} ||= caller();
56
57     $SPEC{$exporting_package} = \%args;
58
59     # canonicalize args
60     my @export_from;
61     if($args{also}){
62         my %seen;
63         my @stack = ($exporting_package);
64
65         while(my $current = shift @stack){
66             push @export_from, $current;
67
68             my $also = $SPEC{$current}{also} or next;
69             push @stack, grep{ !$seen{$_}++ } ref($also) ? @{ $also } : $also;
70         }
71     }
72     else{
73         @export_from = ($exporting_package);
74     }
75
76     my %exports;
77     my @removables;
78     my @all;
79
80     my @init_meta_methods;
81
82     foreach my $package(@export_from){
83         my $spec = $SPEC{$package} or next;
84
85         if(my $as_is = $spec->{as_is}){
86             foreach my $thingy (@{$as_is}){
87                 my($code_package, $code_name, $code);
88
89                 if(ref($thingy)){
90                     $code = $thingy;
91                     ($code_package, $code_name) = Mouse::Util::get_code_info($code);
92                 }
93                 else{
94                     $code_package = $package;
95                     $code_name    = $thingy;
96                     no strict 'refs';
97                     $code         = \&{ $code_package . '::' . $code_name };
98                }
99
100                 push @all, $code_name;
101                 $exports{$code_name} = $code;
102                 if($code_package eq $package){
103                     push @removables, $code_name;
104                 }
105             }
106         }
107
108         if(my $init_meta = $package->can('init_meta')){
109             if(!grep{ $_ == $init_meta } @init_meta_methods){
110                 push @init_meta_methods, $init_meta;
111             }
112         }
113     }
114     $args{EXPORTS}    = \%exports;
115     $args{REMOVABLES} = \@removables;
116
117     $args{groups}{all}     ||= \@all;
118
119     if(my $default_list = $args{groups}{default}){
120         my %default;
121         foreach my $keyword(@{$default_list}){
122             $default{$keyword} = $exports{$keyword}
123                 || Carp::confess(qq{The $exporting_package package does not export "$keyword"});
124         }
125         $args{DEFAULT} = \%default;
126     }
127     else{
128         $args{groups}{default} ||= \@all;
129         $args{DEFAULT}           = $args{EXPORTS};
130     }
131
132     if(@init_meta_methods){
133         $args{INIT_META} = \@init_meta_methods;
134     }
135
136     return (\&do_import, \&do_unimport);
137 }
138
139
140 # the entity of general import()
141 sub do_import {
142     my($package, @args) = @_;
143
144     my $spec = $SPEC{$package}
145         || Carp::confess("The package $package package does not use Mouse::Exporter");
146
147     my $into = _get_caller_package(ref($args[0]) ? shift @args : undef);
148
149     my @exports;
150     my @traits;
151
152     while(@args){
153         my $arg = shift @args;
154         if($arg =~ s/^-//){
155             if($arg eq 'traits'){
156                 push @traits, ref($args[0]) ? @{shift(@args)} : shift(@args);
157             }
158             else {
159                 Mouse::Util::not_supported("-$arg");
160             }
161         }
162         elsif($arg =~ s/^://){
163             my $group = $spec->{groups}{$arg}
164                 || Carp::confess(qq{The $package package does not export the group "$arg"});
165             push @exports, @{$group};
166         }
167         else{
168             push @exports, $arg;
169         }
170     }
171
172     # strict->import;
173     $^H              |= $strict_bits;
174     # warnings->import('all', FATAL => 'recursion');
175     ${^WARNING_BITS} |= $warnings::Bits{all};
176     ${^WARNING_BITS} |= $warnings_extra_bits;
177
178     if($spec->{INIT_META}){
179         my $meta;
180         foreach my $init_meta(@{$spec->{INIT_META}}){
181             $meta = $package->$init_meta(for_class => $into);
182         }
183
184         if(@traits){
185             my $type = (split /::/, ref $meta)[-1]; # e.g. "Class" for "My::Meta::Class"
186             @traits =
187                 map{
188                     ref($_) ? $_
189                             : Mouse::Util::resolve_metaclass_alias($type => $_, trait => 1)
190                 } @traits;
191
192             require Mouse::Util::MetaRole;
193             Mouse::Util::MetaRole::apply_metaroles(
194                 for       => $into,
195                 Mouse::Util::is_a_metarole($into->meta)
196                     ? (role_metaroles  => { role  => \@traits })
197                     : (class_metaroles => { class => \@traits }),
198             );
199         }
200     }
201     elsif(@traits){
202         Carp::confess("Cannot provide traits when $package does not have an init_meta() method");
203     }
204
205     if(@exports){
206         my @export_table;
207         foreach my $keyword(@exports){
208             push @export_table,
209                 $keyword => ($spec->{EXPORTS}{$keyword}
210                     || Carp::confess(qq{The $package package does not export "$keyword"})
211                 );
212         }
213         Mouse::Util::install_subroutines($into, @export_table);
214     }
215     else{
216         Mouse::Util::install_subroutines($into, %{$spec->{DEFAULT}});
217     }
218     return;
219 }
220
221 # the entity of general unimport()
222 sub do_unimport {
223     my($package, $arg) = @_;
224
225     my $spec = $SPEC{$package}
226         || Carp::confess("The package $package does not use Mouse::Exporter");
227
228     my $from = _get_caller_package($arg);
229
230     my $stash = do{
231         no strict 'refs';
232         \%{$from . '::'}
233     };
234
235     for my $keyword (@{ $spec->{REMOVABLES} }) {
236         next if !exists $stash->{$keyword};
237         my $gv = \$stash->{$keyword};
238         if(ref($gv) eq 'GLOB' && *{$gv}{CODE} == $spec->{EXPORTS}{$keyword}){ # make sure it is from us
239             delete $stash->{$keyword};
240         }
241     }
242     return;
243 }
244
245 sub _get_caller_package {
246     my($arg) = @_;
247
248     # We need one extra level because it's called by import so there's a layer
249     # of indirection
250     if(ref $arg){
251         return defined($arg->{into})       ? $arg->{into}
252              : defined($arg->{into_level}) ? scalar caller(1 + $arg->{into_level})
253              :                               scalar caller(1);
254     }
255     else{
256         return scalar caller(1);
257     }
258 }
259
260 #sub _spec{ %SPEC }
261
262 1;
263 __END__
264
265 =head1 NAME
266
267 Mouse::Exporter - make an import() and unimport() just like Mouse.pm
268
269 =head1 VERSION
270
271 This document describes Mouse version 0.70
272
273 =head1 SYNOPSIS
274
275     package MyApp::Mouse;
276
277     use Mouse ();
278     use Mouse::Exporter;
279
280     Mouse::Exporter->setup_import_methods(
281       as_is     => [ 'has_rw', 'other_sugar', \&Some::Random::thing ],
282       also      => 'Mouse',
283     );
284
285     sub has_rw {
286         my $meta = caller->meta;
287         my ( $name, %options ) = @_;
288         $meta->add_attribute(
289           $name,
290           is => 'rw',
291           %options,
292         );
293     }
294
295     # then later ...
296     package MyApp::User;
297
298     use MyApp::Mouse;
299
300     has 'name';
301     has_rw 'size';
302     thing;
303
304     no MyApp::Mouse;
305
306 =head1 DESCRIPTION
307
308 This module encapsulates the exporting of sugar functions in a
309 C<Mouse.pm>-like manner. It does this by building custom C<import>,
310 C<unimport> methods for your module, based on a spec you provide.
311
312 Note that C<Mouse::Exporter> does not provide the C<with_meta> option,
313 but you can easily get the metaclass by C<< caller->meta >> as L</SYNOPSIS> shows.
314
315 =head1 METHODS
316
317 =head2 C<< setup_import_methods( ARGS ) >>
318
319 =head2 C<< build_import_methods( ARGS ) -> (\&import, \&unimport) >>
320
321 =head1 SEE ALSO
322
323 L<Moose::Exporter>
324
325 =cut
326