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.