NAME
    Sub::Implant - Make a named sub out of a subref

VERSION
    Version 1.01

    # remainder of POD after __END__

SYNOPSIS
        use Sub::Implant;

        sub original { (caller 0)[3] }
        say original(); # 'main::original'
        implant 'Some::Package', 'implanted', \ &original;
        say Some::Package::implanted(); # still 'main::original';

        my $anon_orig = sub { (caller 0)[3] };
        say $anon_orig->(); # 'main::__ANON__';
        implant 'Some::Package::also_implanted', $anon_orig;
        say Some::Package::also_implanted(); # now 'Some::Package::also_implanted'

EXPORT
    The function "implant" is exported by default. It can be imported under
    a different name by specifying

        use Sub::Implant implant, {as => 'other_name'};

SUBROUTINES
    "Sub::Implant" puts the mechanics of inserting a subref in a symbol
    table and the action of assigning its internal name together under the
    convenient interface of "implant(...)". See also "ACKNOWLEDGEMENTS"
    below.

    "implant $qualified_name, $subref, %opt"
        Makes the subroutine $subref available under the name
        $qualified_name. If $qualified_name doesn't contain a "::" (that is,
        it isn't really qualified), it will be qualified with the name of
        the calling package.

    "implant $package, $name, $subref, %opt"
        Makes the subroutine $subref available under the name
        "${package}::$name". In this form $name can't also be qualified, it
        is a fatal error if it contains '::'

    If $subref is anonymous, "implant" will set its internal name (the one
    seen by "caller") to the new name. If $subref already has a name
    (originally or by an earlier call to "implant") that name will remain
    unchanged.

    If the target of "implant" is already defined, it emits a warning when
    it is overwritten. Specifying "redef => 1" in %opt suppresses the
    warning.

    If an implanted subref should remain anonymous for some reason, you can
    switch off the naming mechanism with "name => 0" in %opt.

EXAMPLE
    "Sub::Implant" is its own first customer in that it uses "implant" to
    export itself to client modules. Here is how:

        # Basing ->import on ->import_into has nothing to do with
        # Sub::Implant, it's considered good style by some, yours
        # truly included

        sub import {
            my $class = shift;
            $class->_import_into(scalar caller, @_);
        }

        sub _import_into {
            my $class = shift;
            my ($client, @arg) = @_;
            unshift @arg, qw(implant) unless @arg; # default export
            my %export = (                         # provided exports
                implant => \ &implant,
            );

            while ( @arg ) {
                my $export = shift @arg;
                my $code = $export{$export} or croak(
                    "$export is not exported by the $class module"
                );
                # accept export options if given
                my %opt  = %{ shift @arg } if ref $arg[0] eq 'HASH';
                # we only understand the 'as' option
                my $name = $opt{as} // $export;
                implant($client, $name, $code);
            }
        }

    While "Sub::Implant" only exports a single subroutine, you can see that
    it can easily be amended to export more by putting more in the %export
    hash.

AUTHOR
    Anno Siegel, "<anno5 at mac.com>"

BUGS
    There is no way to remove an implanted sub from a package.

    If you find bugs or have feature requests, please report them to
    "bug-sub-implant at rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Implant>. I will be
    notified, and then you'll automatically be notified of progress on your
    bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc Sub::Implant

    You can also look for information at:

    *   RT: CPAN's request tracker (report bugs here)

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sub-Implant>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/Sub-Implant>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/Sub-Implant>

    *   Search CPAN

        <http://search.cpan.org/dist/Sub-Implant/>

ACKNOWLEDGEMENTS
    I have to thank Matthijs van Duin for the "Sub::Name" module. Without
    his prior work the setting of the internal name by "implant" wouldn't
    exist. "Sub::Implant" comes with a slightly modified version of
    "Sub::Name" of its own, so "Sub::Name" doesn't appear among the
    prerequisites of "Sub::Implant".

LICENSE AND COPYRIGHT
    Copyright 2012 Anno Siegel.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.