Tweak doc changes for role_type & class_type
[gitmo/Moose.git] / lib / Moose / Exporter.pm
index 80f77a1..9bf666c 100644 (file)
@@ -3,28 +3,19 @@ package Moose::Exporter;
 use strict;
 use warnings;
 
-our $VERSION = '1.12';
-our $XS_VERSION = $VERSION;
-$VERSION = eval $VERSION;
-our $AUTHORITY = 'cpan:STEVAN';
-
 use Class::MOP;
 use List::MoreUtils qw( first_index uniq );
-use Moose::Deprecated;
 use Moose::Util::MetaRole;
+use Scalar::Util qw(reftype);
 use Sub::Exporter 0.980;
 use Sub::Name qw(subname);
 
-use XSLoader;
-
-XSLoader::load( 'Moose', $XS_VERSION );
-
 my %EXPORT_SPEC;
 
 sub setup_import_methods {
     my ( $class, %args ) = @_;
 
-    my $exporting_package = $args{exporting_package} ||= caller();
+    $args{exporting_package} ||= caller();
 
     $class->build_import_methods(
         %args,
@@ -50,12 +41,7 @@ sub build_import_methods {
         $is_reexport,
     );
 
-    my $exporter = Sub::Exporter::build_exporter(
-        {
-            exports => $exports,
-            groups  => { default => [':all'] }
-        }
-    );
+    my $exporter = $class->_make_exporter($exports, $is_reexport);
 
     my %methods;
     $methods{import} = $class->_make_import_sub(
@@ -89,6 +75,49 @@ sub build_import_methods {
     return ( $methods{import}, $methods{unimport}, $methods{init_meta} );
 }
 
+sub _make_exporter {
+    my ($class, $exports, $is_reexport) = @_;
+
+    return Sub::Exporter::build_exporter(
+        {
+            exports   => $exports,
+            groups    => { default => [':all'] },
+            installer => sub {
+                my ($arg, $to_export) = @_;
+                my $meta = Class::MOP::class_of($arg->{into});
+
+                goto &Sub::Exporter::default_installer unless $meta;
+
+                # don't overwrite existing symbols with our magically flagged
+                # version of it if we would install the same sub that's already
+                # in the importer
+
+                my @filtered_to_export;
+                my %installed;
+                for (my $i = 0; $i < @{ $to_export }; $i += 2) {
+                    my ($as, $cv) = @{ $to_export }[$i, $i + 1];
+
+                    next if !ref($as)
+                         && $meta->has_package_symbol('&' . $as)
+                         && $meta->get_package_symbol('&' . $as) == $cv;
+
+                    push @filtered_to_export, $as, $cv;
+                    $installed{$as} = 1 unless ref $as;
+                }
+
+                Sub::Exporter::default_installer($arg, \@filtered_to_export);
+
+                for my $name ( keys %{$is_reexport} ) {
+                    no strict 'refs';
+                    no warnings 'once';
+                    next unless exists $installed{$name};
+                    _flag_as_reexport( \*{ join q{::}, $arg->{into}, $name } );
+                }
+            },
+        }
+    );
+}
+
 {
     my $seen = {};
 
@@ -98,7 +127,7 @@ sub build_import_methods {
 
         local %$seen = ( $exporting_package => 1 );
 
-        return uniq( _follow_also_real($exporting_package) );
+        return reverse uniq( _follow_also_real($exporting_package) );
     }
 
     sub _follow_also_real {
@@ -130,11 +159,35 @@ sub build_import_methods {
     }
 }
 
+sub _parse_trait_aliases {
+    my $class   = shift;
+    my ($package, $aliases) = @_;
+
+    my @ret;
+    for my $alias (@$aliases) {
+        my $name;
+        if (ref($alias)) {
+            reftype($alias) eq 'ARRAY'
+                or Moose->throw_error(reftype($alias) . " references are not "
+                                    . "valid arguments to the 'trait_aliases' "
+                                    . "option");
+
+            ($alias, $name) = @$alias;
+        }
+        else {
+            ($name = $alias) =~ s/.*:://;
+        }
+        push @ret, subname "${package}::${name}" => sub () { $alias };
+    }
+
+    return @ret;
+}
+
 sub _make_sub_exporter_params {
     my $class           = shift;
     my $packages        = shift;
     my $export_recorder = shift;
-    my $is_reexport  = shift;
+    my $is_reexport     = shift;
 
     my %exports;
 
@@ -168,7 +221,10 @@ sub _make_sub_exporter_params {
             );
         }
 
-        for my $name ( @{ $args->{as_is} } ) {
+        my @extra_exports = $class->_parse_trait_aliases(
+            $package, $args->{trait_aliases},
+        );
+        for my $name ( @{ $args->{as_is} }, @extra_exports ) {
             my ( $sub, $coderef_name );
 
             if ( ref $name ) {
@@ -308,7 +364,7 @@ sub _make_import_sub {
     my $exporting_package = shift;
     my $exporter          = shift;
     my $exports_from      = shift;
-    my $is_reexport    = shift;
+    my $is_reexport       = shift;
 
     return sub {
 
@@ -329,6 +385,9 @@ sub _make_import_sub {
             = Moose::Util::resolve_metaclass_alias( 'Class' => $metaclass )
             if defined $metaclass && length $metaclass;
 
+        my $meta_name;
+        ( $meta_name, @_ ) = _strip_meta_name(@_);
+
         # Normally we could look at $_[0], but in some weird cases
         # (involving goto &Moose::import), $_[0] ends as something
         # else (like Squirrel).
@@ -352,7 +411,11 @@ sub _make_import_sub {
             # Moose::Exporter, which in turn sets $CALLER, so we need
             # to protect against that.
             local $CALLER = $CALLER;
-            $c->init_meta( for_class => $CALLER, metaclass => $metaclass );
+            $c->init_meta(
+                for_class => $CALLER,
+                metaclass => $metaclass,
+                meta_name => $meta_name,
+            );
             $did_init_meta = 1;
         }
 
@@ -381,17 +444,11 @@ sub _make_import_sub {
         }
 
         $class->$exporter( $extra, @args );
-
-        for my $name ( keys %{$is_reexport} ) {
-            no strict 'refs';
-            no warnings 'once';
-            _flag_as_reexport( \*{ join q{::}, $CALLER, $name } );
-        }
     };
 }
 
 sub _strip_traits {
-    my $idx = first_index { $_ eq '-traits' } @_;
+    my $idx = first_index { ( $_ || '' ) eq '-traits' } @_;
 
     return ( [], @_ ) unless $idx >= 0 && $#_ >= $idx + 1;
 
@@ -405,7 +462,7 @@ sub _strip_traits {
 }
 
 sub _strip_metaclass {
-    my $idx = first_index { $_ eq '-metaclass' } @_;
+    my $idx = first_index { ( $_ || '' ) eq '-metaclass' } @_;
 
     return ( undef, @_ ) unless $idx >= 0 && $#_ >= $idx + 1;
 
@@ -416,6 +473,18 @@ sub _strip_metaclass {
     return ( $metaclass, @_ );
 }
 
+sub _strip_meta_name {
+    my $idx = first_index { ( $_ || '' ) eq '-meta_name' } @_;
+
+    return ( 'meta', @_ ) unless $idx >= 0 && $#_ >= $idx + 1;
+
+    my $meta_name = $_[ $idx + 1 ];
+
+    splice @_, $idx, 2;
+
+    return ( $meta_name, @_ );
+}
+
 sub _apply_meta_traits {
     my ( $class, $traits ) = @_;
 
@@ -466,7 +535,7 @@ sub _make_unimport_sub {
     my $exporting_package = shift;
     my $exports           = shift;
     my $export_recorder   = shift;
-    my $is_reexport    = shift;
+    my $is_reexport       = shift;
 
     return sub {
         my $caller = scalar caller();
@@ -484,7 +553,7 @@ sub _remove_keywords {
     my $package          = shift;
     my $keywords         = shift;
     my $recorded_exports = shift;
-    my $is_reexport   = shift;
+    my $is_reexport      = shift;
 
     no strict 'refs';
 
@@ -572,11 +641,9 @@ sub import {
 
 1;
 
-__END__
-
-=head1 NAME
+# ABSTRACT: make an import() and unimport() just like Moose.pm
 
-Moose::Exporter - make an import() and unimport() just like Moose.pm
+__END__
 
 =head1 SYNOPSIS
 
@@ -678,6 +745,14 @@ removed by the C<unimport> method. The reason for this is we cannot know if
 the caller I<also> explicitly imported the sub themselves, and therefore wants
 to keep it.
 
+=item * trait_aliases => [ ... ]
+
+This is a list of package names which should have shortened aliases exported,
+similar to the functionality of L<aliased>. Each element in the list can be
+either a package name, in which case the export will be named as the last
+namespace component of the package, or an arrayref, whose first element is the
+package to alias to, and second element is the alias to export.
+
 =item * also => $name or \@names
 
 This is a list of modules which contain functions that the caller
@@ -708,6 +783,10 @@ C<unimport>, and C<init_meta>. Calling C<setup_import_methods> is equivalent
 to calling C<build_import_methods> with C<< install => [qw(import unimport
 init_meta)] >> except that it doesn't also return the methods.
 
+The C<import> method is built using L<Sub::Exporter>. This means that it can
+take a hashref of the form C<< { into => $package } >> to specify the package
+it operates on.
+
 Used by C<setup_import_methods>.
 
 =back
@@ -735,29 +814,32 @@ Keep in mind that C<build_import_methods> will return an C<init_meta>
 method for you, which you can also call from within your custom
 C<init_meta>:
 
-  my ( $import, $unimport, $init_meta ) =
-      Moose::Exporter->build_import_methods( ... );
+  my ( $import, $unimport, $init_meta )
+      = Moose::Exporter->build_import_methods(...);
 
   sub import {
-     my $class = shift;
+      my $class = shift;
 
-     ...
+      ...
 
-     $class->$import(...);
+      # You can either pass an explicit package to import into ...
+      $class->$import( { into => scalar(caller) }, ... );
 
-     ...
+      ...;
   }
 
+  # ... or you can use 'goto' to provide the correct caller info to the
+  # generated method
   sub unimport { goto &$unimport }
 
   sub init_meta {
-     my $class = shift;
+      my $class = shift;
 
-     ...
+      ...
 
-     $class->$init_meta(...);
+      $class->$init_meta(...);
 
-     ...
+      ...
   }
 
 =head1 METACLASS TRAITS
@@ -778,20 +860,4 @@ a metaclass for the caller is an error.
 
 See L<Moose/BUGS> for details on reporting bugs.
 
-=head1 AUTHOR
-
-Dave Rolsky E<lt>autarch@urth.orgE<gt>
-
-This is largely a reworking of code in Moose.pm originally written by
-Stevan Little and others.
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2009 by Infinity Interactive, Inc.
-
-L<http://www.iinteractive.com>
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
 =cut