File Coverage

blib/lib/Importer/Zim/Unit.pm

Criterion	Covered	Total	%
statement	21	27	77.7
branch	1	6	16.6
condition	0	3	0.0
subroutine	8	9	88.8
pod	0	1	0.0
total	30	46	65.2

package Importer::Zim::Unit;
$Importer::Zim::Unit::VERSION = '0.6.0';
# ABSTRACT: Import functions with compilation unit scope

use 5.010001;

use Devel::Hook ();
use Sub::Replace 0.2.0 ();

use Importer::Zim::Utils 0.8.0 qw(DEBUG );

sub import {
    require Importer::Zim::Base;
    Importer::Zim::Base->VERSION('0.12.0');
    goto &Importer::Zim::Base::import_into;
}

sub export_to {
    my $t = shift;
    @_ = %{ $_[0] } if @_ == 1 && ref $_[0] eq 'HASH';
    @_ = map { $_ & 1 ? $_[$_] : "${t}::$_[$_]" } 0 .. $#_;
    goto &_export_to;
}

sub _export_to {
    my $old = Sub::Replace::sub_replace(@_);

    # Clean it up after compilation
    Devel::Hook->unshift_UNITCHECK_hook(
        sub {
            warn qq{  Restoring @{[map qq{"$_"}, sort keys %$old]}\n}
              if DEBUG;
            Sub::Replace::sub_replace($old);
        }
    ) if %$old;
}

no Importer::Zim::Utils qw(DEBUG );

1;

#pod =encoding utf8
#pod
#pod =head1 SYNOPSIS
#pod
#pod     use Importer::Zim::Unit 'Scalar::Util' => 'blessed';
#pod     use Importer::Zim::Unit 'Scalar::Util' =>
#pod       ( 'blessed' => { -as => 'typeof' } );
#pod
#pod     use Importer::Zim::Unit 'Mango::BSON' => ':bson';
#pod
#pod     use Importer::Zim::Unit 'Foo' => { -version => '3.0' } => 'foo';
#pod
#pod     use Importer::Zim::Unit 'SpaceTime::Machine' => [qw(robot rubber_pig)];
#pod
#pod =head1 DESCRIPTION
#pod
#pod     "I'm gonna roll around on the floor for a while. KAY?"
#pod       – GIR
#pod
#pod This is a backend for L which makes imported
#pod symbols available during compilation.
#pod
#pod Unlike L, it works for perls before 5.18.
#pod Unlike L which plays with lexical subs,
#pod this meddles with the symbol tables for a (hopefully short)
#pod time interval.
#pod
#pod =head1 HOW IT WORKS
#pod
#pod The statement
#pod
#pod     use Importer::Zim::Unit 'Foo' => 'foo';
#pod
#pod works sort of
#pod
#pod     use Sub::Replace;
#pod
#pod     my $_OLD_SUBS;
#pod     BEGIN {
#pod         require Foo;
#pod         $_OLD_SUBS = Sub::Replace::sub_replace('foo' => \&Foo::foo);
#pod     }
#pod
#pod     UNITCHECK {
#pod         Sub::Replace::sub_replace($_OLD_SUBS);
#pod     }
#pod
#pod That means:
#pod
#pod =over 4
#pod
#pod =item *
#pod
#pod Imported subroutines are installed into the caller namespace at compile time.
#pod
#pod =item *
#pod
#pod Imported subroutines are cleaned up just after the unit which defined
#pod them has been compiled.
#pod
#pod =back
#pod
#pod See L<< perlsub /BEGIN, UNITCHECK, CHECK, INIT and END >> for
#pod the concept of "compilation unit" which is relevant here.
#pod
#pod See L for a few gotchas about why this is not simply done
#pod with Perl statements such as
#pod
#pod     *foo = \&Foo::foo;
#pod
#pod =head1 DEBUGGING
#pod
#pod You can set the C environment variable
#pod for get some diagnostics information printed to C.
#pod
#pod     IMPORTER_ZIM_DEBUG=1
#pod
#pod =head1 SEE ALSO
#pod
#pod L
#pod
#pod L<< perlsub /BEGIN, UNITCHECK, CHECK, INIT and END >>
#pod
#pod L
#pod
#pod L
#pod
#pod =cut

__END__