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 <[email protected]>

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.

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.