NAME Package::Pkg - Handy package munging utilities VERSION version 0.0020 SYNOPSIS First, import a new keyword: "pkg" use Package::Pkg; Package name formation: pkg->name( 'Xy', 'A' ) # Xy::A pkg->name( $object, qw/ Cfg / ); # (ref $object)::Cfg Subroutine installation: pkg->install( sub { ... } => 'MyPackage::myfunction' ); # myfunction in MyPackage is now useable MyPackage->myfunction( ... ); Subroutine exporting: package MyPackage; use Package::Pkg; sub this { ... } # Setup an exporter (literally sub import { ... }) for # MyPackage, exporting 'this' and 'that' pkg->export( that => sub { ... }, 'this' ); package main; use MyPackage; this( ... ); that( ... ); DESCRIPTION Package::Pkg is a collection of useful, miscellaneous package-munging utilities. Functionality is accessed via the imported "pkg" keyword, although you can also invoke functions directly from the package ("Package::Pkg") USAGE pkg->install( ... ) Install a subroutine, similar to Sub::Install This method takes a number of parameters and also has a two- and three-argument form (see below) # Install an anonymous subroutine as Banana::magic pkg->install( code => sub { ... } , as => 'Banana::magic' ) pkg->install( code => sub { ... } , into => 'Banana::magic' ) # Bzzzt! Throws an error! # Install the subroutine Apple::xyzzy as Banana::magic pkg->install( code => 'Apple::xyzzy', as => 'Banana::magic' ) pkg->install( code => 'Apple::xyzzy', into => 'Banana', as => 'magic' ) pkg->install( from => 'Apple', code => 'xyzzy', as => 'Banana::magic' ) pkg->install( from => 'Apple', code => 'xyzzy', into => 'Banana', as => 'magic' ) # Install the subroutine Apple::xyzzy as Banana::xyzzy pkg->install( code => 'Apple::xyzzy', as => 'Banana::xyzzy' ) pkg->install( code => 'Apple::xyzzy', into => 'Banana' ) pkg->install( from => 'Apple', code => 'xyzzy', as => 'Banana::xyzzy' ) pkg->install( from => 'Apple', code => 'xyzzy', into => 'Banana' ) With implicit "from" (via "caller()") package Apple; sub xyzzy { ... } # Install the subroutine Apple::xyzzy as Banana::xyzzy pkg->install( code => 'xyzzy', as => 'Banana::xyzzy' ) # 'from' is implicitly 'Apple' pkg->install( code => \&xyzzy, as => 'Banana::xyzzy' ) Acceptable parameters are: code A subroutine reference, A package-with-name identifier, or The name of a subroutine in the calling package from (optional) A package identifier If :code is an identifier, then :from is the package where the subroutine can be found If :code is an identifier and :from is not given, then :from is assumed to be the calling package (via caller()) as The name of the subroutine to install as. Can be a simple name (when paired with :into) or a full package-with-name into (optional) A package identifier If :as is given, then the full name of the installed subroutine is (:into)::(:as) If :as is not given and we can derive a simple name from :code (It is a package-with-name identifier), then :as will be the name identifier part of :code pkg->install( $code => $as ) This is the two-argument form of subroutine installation Install $code subroutine as $as pkg->install( sub { ... } => 'Banana::xyzzy' ) pkg->install( 'Scalar::Util::blessed' => 'Banana::xyzzy' ) pkg->install( 'Scalar::Util::blessed' => 'Banana::' ) pkg->install( sub { ... } => 'Banana::' ) # Bzzzt! Throws an error! $code should be: * A CODE reference sub { ... } * A package-with-name identifier Scalar::Util::blessed * The name of a subroutine in the calling package sub xyzzy { ... } pkg->install( 'xyzzy' => ... ) $as should be: * A package-with-name identifier Acme::Xyzzy::magic * A package identifier (with a trailing ::) Acme::Xyzzy:: pkg->install( $code => $into, $as ) This is the three-argument form of subroutine installation pkg->install( sub { ... } => 'Banana', 'xyzzy' ) pkg->install( sub { ... } => 'Banana::', 'xyzzy' ) pkg->install( 'Scalar::Util::blessed' => 'Banana', 'xyzzy' ) pkg->install( 'Scalar::Util::blessed' => 'Banana::', 'xyzzy' ) $code can be the same as the two argument form $into should be: * A package identifier (trailing :: is optional) Acme::Xyzzy:: Acme::Xyzzy $as should be: * A name (the name of the subroutine) xyzzy magic $package = pkg->name( $part, [ $part, ..., $part ] ) Return a namespace composed by joining each $part with "::" Superfluous/redundant "::" are automatically cleaned up and stripped from the resulting $package If the first part leads with a "::", the the calling package will be prepended to $package pkg->name( 'Xy', 'A::', '::B' ) # Xy::A::B pkg->name( 'Xy', 'A::' ) # Xy::A:: { package Zy; pkg->name( '::', 'A::', '::B' ) # Zy::A::B pkg->name( '::Xy::A::B' ) # Zy::Xy::A::B } In addition, if any part is blessed, "name" will resolve that part to the package that the part makes reference to: my $object = bless {}, 'Xyzzy'; pkg->name( $object, qw/ Cfg / ); # Xyzzy::Cfg SEE ALSO Sub::Install Sub::Exporter AUTHOR Robert Krimen <robertkrimen@gmail.com> COPYRIGHT AND LICENSE This software is copyright (c) 2012 by Robert Krimen. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.