File Coverage

blib/lib/Sub/Exporter/Lexical.pm

Criterion	Covered	Total	%
statement	18	22	81.8
branch	3	8	37.5
condition			n/a
subroutine	6	6	100.0
pod	1	1	100.0
total	28	37	75.6

use v5.12.0;
use warnings;
package Sub::Exporter::Lexical 1.001;
# ABSTRACT: to export lexically-available subs with Sub::Exporter

# I know about if.pm!  But we can't use it here because "use Lexical::Sub" will
# call import and then it dies "does no default importation".  And then what
# about this *utterly ridiculous* require?  Well, that's to avoid the prereq
# scanner picking up Lexical::Sub, which I do not want to just RemovePrereqs
# on, because that runs after the thing that adds optional prereqs.
BEGIN {
  if ($] <  5.037002) { eval "require Lexical::Sub;" || die $@ }
  else                { require builtin;      }
}

use Sub::Exporter -setup => {
  exports => [ qw(lexical_installer) ],
};

#pod =head1 SYNOPSIS
#pod
#pod In an exporting library:
#pod
#pod   package Some::Toolkit;
#pod
#pod   use Sub::Exporter -setup => {
#pod     exports   => [ qw(foo bar baz) ],
#pod   };
#pod
#pod   sub foo { ... }
#pod   sub bar { ... }
#pod   sub baz { ... }
#pod
#pod In an importing library:
#pod
#pod   package Vehicle::Autobot;
#pod
#pod   use Sub::Exporter::Lexical lexical_installer => { -as => 'lex' };
#pod
#pod   ...;
#pod
#pod   {
#pod     use Some:::Toolkit { installer => lex }, qw(foo bar);
#pod
#pod     foo(1,2,3);
#pod     my $x = bar;
#pod
#pod     ...
#pod   };
#pod
#pod   # ... and here, foo and bar are no longer available ...
#pod
#pod =head1 DESCRIPTION
#pod
#pod Sub::Exporter::Lexical provides an alternate installer for
#pod L.  Installers are documented in Sub::Exporter's
#pod documentation; all you need to know is that by using Sub::Exporter::Lexical's
#pod installer, you can import routines into a lexical scope that will be cleaned up
#pod when that scope ends.
#pod
#pod There are two places it makes sense to use the lexical installer: when
#pod configuring Sub::Exporter in your exporting package or when importing from a
#pod package that uses Sub::Exporter.  For the first case, do something like this:
#pod
#pod   package Some::Toolkit;
#pod   use Sub::Exporter::Lexical ();
#pod   use Sub::Exporter -setup => {
#pod     exports   => [ ... ],
#pod     installer => Sub::Exporter::Lexical::lexical_installer,
#pod   };
#pod
#pod For the second:
#pod
#pod   package My::Library;
#pod
#pod   use Sub::Exporter::Lexical ();
#pod   use Some::Toolkit
#pod     { installer => Sub::Exporter::Lexical::lexical_installer },
#pod     qw(foo bar baz);
#pod
#pod =head1 EXPORTS
#pod
#pod Sub::Exporter::Lexical offers only one routine for export, and it may also
#pod be called by its full package name:
#pod
#pod =head2 lexical_installer
#pod
#pod This routine returns an installer suitable for use as the C argument
#pod to Sub::Exporter.  It installs all requested routines as usual, but marks them
#pod to be removed from the target package as soon as the block in which it was
#pod called is complete.
#pod
#pod It does not affect the behavior of routines exported into scalar references.
#pod
#pod B, it does not affect scopes in which it is invoked at
#pod runtime, rather than compile time.  B  It means that this
#pod works:
#pod
#pod   {
#pod     use Some::Toolkit { installer => lexical_installer }, qw(foo);
#pod     foo(1,2,3);
#pod   }
#pod
#pod   foo(); # this dies
#pod
#pod ...but this does not...
#pod
#pod   {
#pod     require Some::Toolkit;
#pod     Some::Toolkit->import({ installer => lexical_installer }, qw(foo));
#pod     foo(1,2,3);
#pod   }
#pod
#pod   foo(); # this does not die, even though you might expect it to
#pod
#pod Finally, you can't supply a C<< -as => \$var >> install destination yet.
#pod
#pod =cut

sub lexical_installer {
  sub {
    my ($arg, $to_export) = @_;

    my $into = $arg->{into};

    my @pairs = @$to_export;
    while (my ($name, $code) = splice @pairs, 0, 2) {
      if (ref $name) {
        # We could implement this easily, but haven't. -- rjbs, 2013-11-24
        Carp::cluck("can't import to variable with lexical installer (yet)");
        next;
      }

      if ($] >= 5.037002) { builtin::export_lexically($name, $code); }
      else                { Lexical::Sub->import($name, $code); }
    }
  };
}

1;

__END__