Package::Pkg(3pm)					User Contributed Perl Documentation					 Package::Pkg(3pm)

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:

       o   A CODE reference

	       sub { ... }

       o   A package-with-name identifier

	       Scalar::Util::blessed

       o   The name of a subroutine in the calling package

	       sub xyzzy { ... }

	       pkg->install( 'xyzzy' => ... )

       $as should be:

       o   A package-with-name identifier

	       Acme::Xyzzy::magic

       o   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:

       o   A package identifier (trailing :: is optional)

	       Acme::Xyzzy::

	       Acme::Xyzzy

       $as should be:

       o   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.

perl v5.14.2							    2012-06-15							 Package::Pkg(3pm)