Expose optimal_import

3 files changed, 30 insertions, 5 deletions

diff --git a/Changes b/Changes
index 7a0a1ec..c69949d 100644
--- a/Changes
+++ b/Changes
@@ -1,5 +1,7 @@
 {{$NEXT}}
 
+    - Expose optimal_import()
+
 0.011     2016-01-26 15:55:46-08:00 America/Los_Angeles
 
     - no changes from last trial
diff --git a/lib/Importer.pm b/lib/Importer.pm
index c0695b8..2577b9d 100644
--- a/lib/Importer.pm
+++ b/lib/Importer.pm
@@ -12,6 +12,8 @@ my %SIG_TO_SLOT = (
     '*' => 'GLOB',
 );
 
+our @EXPORT_OK = qw/optimal_import/;
+
 our %IMPORTED;
 
 # This will be used to check if an import arg is a version number
@@ -42,7 +44,7 @@ sub import {
     my $file = _mod_to_file($from);
     _load_file(\@caller, $file) unless $INC{$file};
 
-    return if _optimal_import($from, $caller[0], \@caller, @args);
+    return if optimal_import($from, $caller[0], \@caller, @args);
 
     my $self = $class->new(
         from   => $from,
@@ -81,7 +83,7 @@ sub import_into {
     my $file = _mod_to_file($from);
     _load_file(\@caller, $file) unless $INC{$file};
 
-    return if _optimal_import($from, $into, \@caller, @args);
+    return if optimal_import($from, $into, \@caller, @args);
 
     my $self = $class->new(
         from   => $from,
@@ -635,7 +637,7 @@ my %HEAVY_VARS = (
     EXPORT_MAGIC  => 'HASH',  # Origin package has magic to apply post-export
 );
 
-sub _optimal_import {
+sub optimal_import {
     my ($from, $into, $caller, @args) = @_;
 
     defined(*{"$from\::$_"}{$HEAVY_VARS{$_}}) and return 0 for keys %HEAVY_VARS;
@@ -1263,6 +1265,27 @@ imports then only the LAST one will be used.
 
 =back
 
+=head1 FUNCTIONS
+
+These can be imported:
+
+    use Importer 'Importer' => qw/optimal_import/;
+
+=over 4
+
+=item $bool = optimal_import($from, $into, \@caller, @imports)
+
+This function will attempt to import C<@imports> from the C<$from> package into
+the C<$into> package. C<@caller> needs to have a package name, filename, and
+line number. If this function fails then no exporting will actually happen.
+
+If the import is successful this will return true.
+
+If the import is unsuccessful this will return false, and no modifications to
+the symbol table will occur.
+
+=back
+
 =head1 SOURCE
 
 The source code repository for symbol can be found at
diff --git a/t/units.t b/t/units.t
index 292e02d..35da589 100644
--- a/t/units.t
+++ b/t/units.t
@@ -933,14 +933,14 @@ require Fake::File::That::Better::Not::Exist::SAGSDGDS;
     );
 };
 
-subtest _optimal_import => sub {
+subtest optimal_import => sub {
     {
         package Fake::ForOptimal::A;
         our @EXPORT = qw/foo &bar $ZAP %ZAP @ZAP/;
         sub foo { 'foo' }
         sub bar { 'bar' }
     }
-    my $optimal = $CLASS->can('_optimal_import');
+    my $optimal = $CLASS->can('optimal_import');
 
     ok($optimal->('Fake::ForOptimal::A', 'FDestA', ['F', 'F.pm', 4], qw/foo/), "Success");
     can_ok('FDestA', 'foo');