lib/Mouse/Exporter.pm

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