Package::Pkg(3) User Contributed Perl Documentation Package::Pkg(3)NAMEPackage::Pkg - Handy package munging utilities
VERSION
version 0.0019
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( ... );
DESCRIPTIONPackage::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) 2010 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.1 2010-06-12 Package::Pkg(3)
