NAME

Importer::Zim::Unit - Import functions with compilation unit scope

VERSION

version 0.5.0

SYNOPSIS

    use Importer::Zim::Unit 'Scalar::Util' => 'blessed';
    use Importer::Zim::Unit 'Scalar::Util' =>
      ( 'blessed' => { -as => 'typeof' } );

    use Importer::Zim::Unit 'Mango::BSON' => ':bson';

    use Importer::Zim::Unit 'Foo' => { -version => '3.0' } => 'foo';

    use Importer::Zim::Unit 'SpaceTime::Machine' => [qw(robot rubber_pig)];

DESCRIPTION

    "I'm gonna roll around on the floor for a while. KAY?"
      – GIR

This is a backend for Importer::Zim which makes imported symbols available during compilation.

Unlike Importer::Zim::Lexical, it works for perls before 5.18. Unlike Importer::Zim::Lexical which plays with lexical subs, this meddles with the symbol tables for a (hopefully short) time interval.

HOW IT WORKS

The statement

    use Importer::Zim::Unit 'Foo' => 'foo';

works sort of

    use Sub::Replace;

    my $_OLD_SUBS;
    BEGIN {
        require Foo;
        $_OLD_SUBS = Sub::Replace::sub_replace('foo' => \&Foo::foo);
    }

    UNITCHECK {
        Sub::Replace::sub_replace($_OLD_SUBS);
    }

That means:

• Imported subroutines are installed into the caller namespace at compile time.

• Imported subroutines are cleaned up just after the unit which defined them has been compiled.

See "BEGIN, UNITCHECK, CHECK, INIT and END" in perlsub for the concept of "compilation unit" which is relevant here.

See Sub::Replace for a few gotchas about why this is not simply done with Perl statements such as

    *foo = \&Foo::foo;

DEBUGGING

You can set the IMPORTER_ZIM_DEBUG environment variable for get some diagnostics information printed to STDERR.

    IMPORTER_ZIM_DEBUG=1

SEE ALSO

Importer::Zim

"BEGIN, UNITCHECK, CHECK, INIT and END" in perlsub

Importer::Zim::Lexical

Importer::Zim::EndOfScope

AUTHOR

Adriano Ferreira <ferreira@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Adriano Ferreira.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Importer::Zim::Unit

perl -MCPAN -e shell
install Importer::Zim::Unit