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