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