NAME
    Import::Into::As - Wrapper around Import::Into that lets you rename
    subs.

DESCRIPTION
    This wrapper provides a new function "import::into::as" which works just
    like "import::into()", except that you can rename the subs being
    exported around.

    This is a wrapper around Import::Into, which is an awesome tool that
    lets you import any module into any other module. The problem is that
    not all modules you are importing from have the ability to rename
    exports. This is not a problem if you are exporting from modules that
    use Sub::Exporter or Exporter::Declare, but it is a problem if you want
    to rename a sub exported from Exporter.

    Note: If you are exporting from modules that allow you to rename the
    exports in their own syntax then you should use that. This module will
    be slower than using the exporters rename syntax when available. This
    module also has some limitations, see the "LIMITATIONS" section.

SYNOPSYS
        use Import::Into::As;

        # Export 'foo' and 'baz' from Some::Exporter into Destination::Package.
        # Rename 'foo' to 'bar' in the process.
        Some::Exporter->import_into_as('Destination::Package', {foo => bar}, qw/foo baz/);

METHODS
  $package->import::into::as($target, \%renames, @arguments);
    $package
        Package to export from.

    $target
        This can be a target package, a call level, or a hashref, see
        "METHODS" in Import::Into for an expanded explanation of $target.

    \%renames
        This must be a hashref where the keys are the names of a subs
        exported by the package, and the values are the new names you want
        them to have.

            { 'export_name' => 'new_name', ... }

    \@arguments
        Import arguments for the package.

HOW IT WORKS
    This package will localize the taget packages namespace, temporarily
    making it empty. This will then use Import::Into to import into the now
    empty namespace. Once the import is complete the new symbol table is
    copied. Once the original symbol table is restored the new imports will
    be placed into the actual namespace, but under the new names.

  WHY IS IT SO COMPLICATED!?
    There are some problems that have to be worked around:

    Not all export tools support export renaming
        This is not something we can directly do anything about, so we have
        to do our own rename post-import.

    It can be hard to determine if an exporter does support renaming
        This makes it hard to defer to the exporter when it is possible.

    There may already be a sub defined in the package with the export name
        This is actually pretty easy to solve. We can look for an existing
        sub for any key in the rename hash, store it, and restore it after
        the import. None of this localizing the package would be necessary
        if this was the last problem.

    There may NOT already be a sub defined in the package with the export
    name
        This is suprisingly a MUCH harder problem to solve. The import
        process will put a sub into the package namespace under the original
        name. We can then copy the sub to the new name easily enough. The
        hard part is removing the sub from the old name, it is surprisingly
        difficult!

LIMITATIONS
    Only subs can be renamed (this may change in the future)
        It would not be difficult to add renaming support for other types,
        but there has not been any need yet.

    Only CODE, SCALAR, HASH, and ARRAY exports are allowed
        Typeglobs have other keys such as "FORMATTER", but the big 4 listed
        here shoudl be sufficient for nearly all use cases.

    Exporting endefined scalars that do not exist in the exporting namespace
    fail
        This is a pretty rare edge case, but it can happen.

        If the exporter does this, then the scalar export will not work:

            sub import {
                my $caller = caller;

                my $FOO = undef;

                *{"$caller\::FOO"} = \$FOO;
            }

        This reasonf or this is that a typeglob always has a refernece to
        undef in the SCALAR slot. We cannot easily check if a scalar was
        imported into a specific name whent he scalar is undef. As a backup
        we check if the reference is the same reference as the one in the
        exporting package, but in cases like the one above that is not
        helpful.

SOURCE
    The source code repository for Import-Into-As can be found at
    http://github.com/exodist/Import-Into-As.

MAINTAINERS
    Chad Granum <exodist@cpan.org>

AUTHORS
    Chad Granum <exodist@cpan.org>

COPYRIGHT
    Copyright 2015 Chad Granum <exodist7@gmail.com>.

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

    See http://dev.perl.org/licenses/

