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