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