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