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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.