Tweaks and documenting Mouse::Exporter

[gitmo/Mouse.git] / lib / Mouse / Exporter.pm

diff --git a/lib/Mouse/Exporter.pm b/lib/Mouse/Exporter.pm
index 5884c68..05bd169 100644 (file)
--- a/lib/Mouse/Exporter.pm
+++ b/lib/Mouse/Exporter.pm
@@ -4,12 +4,21 @@ use warnings;
 
 use Carp qw(confess);
 
-use Mouse::Util qw(get_code_info not_supported);
-
 my %SPEC;
 
 my $strict_bits = strict::bits(qw(subs refs vars));
 
+# it must be "require", because Mouse::Util depends on Mouse::Exporter,
+# which depends on Mouse::Util::import()
+require Mouse::Util;
+
+sub import{
+    $^H              |= $strict_bits;         # strict->import;
+    ${^WARNING_BITS}  = $warnings::Bits{all}; # warnings->import;
+    return;
+}
+
+
 sub setup_import_methods{
     my($class, %args) = @_;
 
@@ -27,7 +36,7 @@ sub setup_import_methods{
             push @export_from, $current;
 
             my $also = $SPEC{$current}{also} or next;
-            push @stack, grep{ !$seen{$_}++ } @{ $also };
+            push @stack, grep{ !$seen{$_}++ } ref($also) ? @{ $also } : $also;
         }
     }
     else{
@@ -50,7 +59,7 @@ sub setup_import_methods{
 
                     if(ref($thingy)){
                         $code = $thingy;
-                        ($code_package, $code_name) = get_code_info($code);
+                        ($code_package, $code_name) = Mouse::Util::get_code_info($code);
                     }
                     else{
                         no strict 'refs';
@@ -76,9 +85,9 @@ sub setup_import_methods{
         $args{EXPORTS}    = \%exports;
         $args{REMOVABLES} = \@removables;
 
-        $args{group}{all}     ||= \@all;
+        $args{groups}{all}     ||= \@all;
 
-        if(my $default_list = $args{group}{default}){
+        if(my $default_list = $args{groups}{default}){
             my %default;
             foreach my $keyword(@{$default_list}){
                 $default{$keyword} = $exports{$keyword}
@@ -87,8 +96,8 @@ sub setup_import_methods{
             $args{DEFAULT} = \%default;
         }
         else{
-            $args{group}{default} ||= \@all;
-            $args{DEFAULT}          = $args{EXPORTS};
+            $args{groups}{default} ||= \@all;
+            $args{DEFAULT}           = $args{EXPORTS};
         }
 
         if(@init_meta_methods){
@@ -115,12 +124,13 @@ sub do_import {
     my $into = _get_caller_package(ref($args[0]) ? shift @args : undef);
 
     my @exports;
+
     foreach my $arg(@args){
         if($arg =~ s/^-//){
-            not_supported "-$arg";
+            Mouse::Util::not_supported("-$arg");
         }
         elsif($arg =~ s/^://){
-            my $group = $spec->{group}{$arg}
+            my $group = $spec->{groups}{$arg}
                 || confess(qq{The $package package does not export the group "$arg"});
             push @exports, @{$group};
         }
@@ -132,7 +142,7 @@ sub do_import {
     $^H              |= $strict_bits;         # strict->import;
     ${^WARNING_BITS}  = $warnings::Bits{all}; # warnings->import;
 
-    if($into eq 'main' && !$spec->{_not_export_to_main}){
+    if($into eq 'main' && !$spec->{_export_to_main}){
         warn qq{$package does not export its sugar to the 'main' package.\n};
         return;
     }
@@ -185,20 +195,20 @@ sub do_unimport {
     return;
 }
 
+# 1 extra level because it's called by import so there's a layer\r
+# of indirection\r
+sub _LEVEL(){ 1 }
+
 sub _get_caller_package {
     my($arg) = @_;
 
-    # 2 extra level because it's called by import so there's a layer\r
-    # of indirection\r
-    my $offset = 1;\r
-
     if(ref $arg){
         return defined($arg->{into})       ? $arg->{into}
-             : defined($arg->{into_level}) ? scalar caller($offset + $arg->{into_level})
-             :                               scalar caller($offset);
+             : defined($arg->{into_level}) ? scalar caller(_LEVEL + $arg->{into_level})
+             :                               scalar caller(_LEVEL);
     }
     else{
-        return scalar caller($offset);
+        return scalar caller(_LEVEL);
     }
 }
 
@@ -208,19 +218,49 @@ __END__
 
 =head1 NAME
 
-Mouse - The Mouse Exporter
+Mouse::Exporter - make an import() and unimport() just like Mouse.pm
 
 =head1 SYNOPSIS
 
-    package MouseX::Foo;
-    use Mouse::Exporter;
-
-    Mouse::Exporter->setup_import_methods(
-
-    );
+    package MyApp::Mouse;\r
+\r
+    use Mouse ();\r
+    use Mouse::Exporter;\r
+\r
+    Mouse::Exporter->setup_import_methods(\r
+      as_is     => [ 'has_rw', 'other_sugar', \&Some::Random::thing ],\r
+      also      => 'Mouse',\r
+    );\r
+\r
+    sub has_rw {
+        my $meta = caller->meta;\r
+        my ( $name, %options ) = @_;\r
+        $meta->add_attribute(\r
+          $name,\r
+          is => 'rw',\r
+          %options,\r
+        );\r
+    }\r
+\r
+    # then later ...\r
+    package MyApp::User;\r
+
+    use MyApp::Mouse;\r
+\r
+    has 'name';\r
+    has_rw 'size';\r
+    thing;\r
+\r
+    no MyApp::Mouse;
 
 =head1 DESCRIPTION
 
+This module encapsulates the exporting of sugar functions in a\r
+C<Mouse.pm>-like manner. It does this by building custom C<import>,\r
+C<unimport> methods for your module, based on a spec you provide.\r
+
+Note that C<Mouse::Exporter> does not provide the C<with_meta> option,
+but you can easily get the metaclass by C<< caller->meta >> as L</SYNOPSIS> shows.
 
 =head1 SEE ALSO