File Coverage

blib/lib/Importer/Zim/EndOfScope.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::EndOfScope;
$Importer::Zim::EndOfScope::VERSION = '0.5.0';
# ABSTRACT: Import functions with compilation block scope

use 5.010001;

use B::Hooks::EndOfScope ();
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 a scope finished compilation
    B::Hooks::EndOfScope::on_scope_end(
        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::EndOfScope 'Scalar::Util' => 'blessed';
#pod     use Importer::Zim::EndOfScope 'Scalar::Util' =>
#pod       ( 'blessed' => { -as => 'typeof' } );
#pod
#pod     use Importer::Zim::EndOfScope 'Mango::BSON' => ':bson';
#pod
#pod     use Importer::Zim::EndOfScope 'Foo' => { -version => '3.0' } => 'foo';
#pod
#pod     use Importer::Zim::EndOfScope 'SpaceTime::Machine' => [qw(robot rubber_pig)];
#pod
#pod =head1 DESCRIPTION
#pod
#pod     "Wait a minute! What planet is this?"
#pod       – Zim
#pod
#pod This is a backend for L which makes
#pod imported symbols available during the compilation of
#pod the surrounding scope.
#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. (This time interval should be even shorter
#pod than the one that applies to L.)
#pod
#pod =head1 HOW IT WORKS
#pod
#pod The statement
#pod
#pod     use Importer::Zim::EndOfScope 'Foo' => 'foo';
#pod
#pod works sort of
#pod
#pod     use B::Hooks::EndOfScope;
#pod
#pod     my $_OLD_SUBS;
#pod     BEGIN {
#pod         require Foo;
#pod         $_OLD_SUBS = Sub::Replace::sub_replace('foo' => \&Foo::foo);
#pod     }
#pod
#pod     on_scope_end {
#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 after perl finished compiling
#pod the surrounding scope.
#pod
#pod =back
#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
#pod
#pod L
#pod
#pod =cut

__END__