| 1 |
NAME |
| 2 |
Package::Pkg - Handy package munging utilities |
| 3 |
|
| 4 |
VERSION |
| 5 |
version 0.0020 |
| 6 |
|
| 7 |
SYNOPSIS |
| 8 |
First, import a new keyword: "pkg" |
| 9 |
|
| 10 |
use Package::Pkg; |
| 11 |
|
| 12 |
Package name formation: |
| 13 |
|
| 14 |
pkg->name( 'Xy', 'A' ) # Xy::A |
| 15 |
pkg->name( $object, qw/ Cfg / ); # (ref $object)::Cfg |
| 16 |
|
| 17 |
Subroutine installation: |
| 18 |
|
| 19 |
pkg->install( sub { ... } => 'MyPackage::myfunction' ); |
| 20 |
|
| 21 |
# myfunction in MyPackage is now useable |
| 22 |
MyPackage->myfunction( ... ); |
| 23 |
|
| 24 |
Subroutine exporting: |
| 25 |
|
| 26 |
package MyPackage; |
| 27 |
|
| 28 |
use Package::Pkg; |
| 29 |
|
| 30 |
sub this { ... } |
| 31 |
|
| 32 |
# Setup an exporter (literally sub import { ... }) for |
| 33 |
# MyPackage, exporting 'this' and 'that' |
| 34 |
pkg->export( that => sub { ... }, 'this' ); |
| 35 |
|
| 36 |
package main; |
| 37 |
|
| 38 |
use MyPackage; |
| 39 |
|
| 40 |
this( ... ); |
| 41 |
|
| 42 |
that( ... ); |
| 43 |
|
| 44 |
DESCRIPTION |
| 45 |
Package::Pkg is a collection of useful, miscellaneous package-munging |
| 46 |
utilities. Functionality is accessed via the imported "pkg" keyword, |
| 47 |
although you can also invoke functions directly from the package |
| 48 |
("Package::Pkg") |
| 49 |
|
| 50 |
USAGE |
| 51 |
pkg->install( ... ) |
| 52 |
Install a subroutine, similar to Sub::Install |
| 53 |
|
| 54 |
This method takes a number of parameters and also has a two- and |
| 55 |
three-argument form (see below) |
| 56 |
|
| 57 |
# Install an anonymous subroutine as Banana::magic |
| 58 |
pkg->install( code => sub { ... } , as => 'Banana::magic' ) |
| 59 |
pkg->install( code => sub { ... } , into => 'Banana::magic' ) # Bzzzt! Throws an error! |
| 60 |
|
| 61 |
# Install the subroutine Apple::xyzzy as Banana::magic |
| 62 |
pkg->install( code => 'Apple::xyzzy', as => 'Banana::magic' ) |
| 63 |
pkg->install( code => 'Apple::xyzzy', into => 'Banana', as => 'magic' ) |
| 64 |
pkg->install( from => 'Apple', code => 'xyzzy', as => 'Banana::magic' ) |
| 65 |
pkg->install( from => 'Apple', code => 'xyzzy', into => 'Banana', as => 'magic' ) |
| 66 |
|
| 67 |
# Install the subroutine Apple::xyzzy as Banana::xyzzy |
| 68 |
pkg->install( code => 'Apple::xyzzy', as => 'Banana::xyzzy' ) |
| 69 |
pkg->install( code => 'Apple::xyzzy', into => 'Banana' ) |
| 70 |
pkg->install( from => 'Apple', code => 'xyzzy', as => 'Banana::xyzzy' ) |
| 71 |
pkg->install( from => 'Apple', code => 'xyzzy', into => 'Banana' ) |
| 72 |
|
| 73 |
With implicit "from" (via "caller()") |
| 74 |
|
| 75 |
package Apple; |
| 76 |
|
| 77 |
sub xyzzy { ... } |
| 78 |
|
| 79 |
# Install the subroutine Apple::xyzzy as Banana::xyzzy |
| 80 |
pkg->install( code => 'xyzzy', as => 'Banana::xyzzy' ) # 'from' is implicitly 'Apple' |
| 81 |
pkg->install( code => \&xyzzy, as => 'Banana::xyzzy' ) |
| 82 |
|
| 83 |
Acceptable parameters are: |
| 84 |
|
| 85 |
code A subroutine reference, |
| 86 |
A package-with-name identifier, or |
| 87 |
The name of a subroutine in the calling package |
| 88 |
|
| 89 |
from (optional) A package identifier |
| 90 |
If :code is an identifier, then :from is the package where |
| 91 |
the subroutine can be found |
| 92 |
If :code is an identifier and :from is not given, then :from |
| 93 |
is assumed to be the calling package (via caller()) |
| 94 |
|
| 95 |
as The name of the subroutine to install as. Can be a simple name |
| 96 |
(when paired with :into) or a full package-with-name |
| 97 |
|
| 98 |
into (optional) A package identifier |
| 99 |
If :as is given, then the full name of the installed |
| 100 |
subroutine is (:into)::(:as) |
| 101 |
|
| 102 |
If :as is not given and we can derive a simple name from |
| 103 |
:code (It is a package-with-name identifier), then :as will be |
| 104 |
the name identifier part of :code |
| 105 |
|
| 106 |
pkg->install( $code => $as ) |
| 107 |
This is the two-argument form of subroutine installation |
| 108 |
|
| 109 |
Install $code subroutine as $as |
| 110 |
|
| 111 |
pkg->install( sub { ... } => 'Banana::xyzzy' ) |
| 112 |
|
| 113 |
pkg->install( 'Scalar::Util::blessed' => 'Banana::xyzzy' ) |
| 114 |
|
| 115 |
pkg->install( 'Scalar::Util::blessed' => 'Banana::' ) |
| 116 |
|
| 117 |
pkg->install( sub { ... } => 'Banana::' ) # Bzzzt! Throws an error! |
| 118 |
|
| 119 |
$code should be: |
| 120 |
|
| 121 |
* A CODE reference |
| 122 |
|
| 123 |
sub { ... } |
| 124 |
|
| 125 |
* A package-with-name identifier |
| 126 |
|
| 127 |
Scalar::Util::blessed |
| 128 |
|
| 129 |
* The name of a subroutine in the calling package |
| 130 |
|
| 131 |
sub xyzzy { ... } |
| 132 |
|
| 133 |
pkg->install( 'xyzzy' => ... ) |
| 134 |
|
| 135 |
$as should be: |
| 136 |
|
| 137 |
* A package-with-name identifier |
| 138 |
|
| 139 |
Acme::Xyzzy::magic |
| 140 |
|
| 141 |
* A package identifier (with a trailing ::) |
| 142 |
|
| 143 |
Acme::Xyzzy:: |
| 144 |
|
| 145 |
pkg->install( $code => $into, $as ) |
| 146 |
This is the three-argument form of subroutine installation |
| 147 |
|
| 148 |
pkg->install( sub { ... } => 'Banana', 'xyzzy' ) |
| 149 |
|
| 150 |
pkg->install( sub { ... } => 'Banana::', 'xyzzy' ) |
| 151 |
|
| 152 |
pkg->install( 'Scalar::Util::blessed' => 'Banana', 'xyzzy' ) |
| 153 |
|
| 154 |
pkg->install( 'Scalar::Util::blessed' => 'Banana::', 'xyzzy' ) |
| 155 |
|
| 156 |
$code can be the same as the two argument form |
| 157 |
|
| 158 |
$into should be: |
| 159 |
|
| 160 |
* A package identifier (trailing :: is optional) |
| 161 |
|
| 162 |
Acme::Xyzzy:: |
| 163 |
|
| 164 |
Acme::Xyzzy |
| 165 |
|
| 166 |
$as should be: |
| 167 |
|
| 168 |
* A name (the name of the subroutine) |
| 169 |
|
| 170 |
xyzzy |
| 171 |
|
| 172 |
magic |
| 173 |
|
| 174 |
$package = pkg->name( $part, [ $part, ..., $part ] ) |
| 175 |
Return a namespace composed by joining each $part with "::" |
| 176 |
|
| 177 |
Superfluous/redundant "::" are automatically cleaned up and stripped |
| 178 |
from the resulting $package |
| 179 |
|
| 180 |
If the first part leads with a "::", the the calling package will be |
| 181 |
prepended to $package |
| 182 |
|
| 183 |
pkg->name( 'Xy', 'A::', '::B' ) # Xy::A::B |
| 184 |
pkg->name( 'Xy', 'A::' ) # Xy::A:: |
| 185 |
|
| 186 |
{ |
| 187 |
package Zy; |
| 188 |
|
| 189 |
pkg->name( '::', 'A::', '::B' ) # Zy::A::B |
| 190 |
pkg->name( '::Xy::A::B' ) # Zy::Xy::A::B |
| 191 |
} |
| 192 |
|
| 193 |
In addition, if any part is blessed, "name" will resolve that part to |
| 194 |
the package that the part makes reference to: |
| 195 |
|
| 196 |
my $object = bless {}, 'Xyzzy'; |
| 197 |
pkg->name( $object, qw/ Cfg / ); # Xyzzy::Cfg |
| 198 |
|
| 199 |
SEE ALSO |
| 200 |
Sub::Install |
| 201 |
|
| 202 |
Sub::Exporter |
| 203 |
|
| 204 |
AUTHOR |
| 205 |
Robert Krimen <[email protected]> |
| 206 |
|
| 207 |
COPYRIGHT AND LICENSE |
| 208 |
This software is copyright (c) 2012 by Robert Krimen. |
| 209 |
|
| 210 |
This is free software; you can redistribute it and/or modify it under |
| 211 |
the same terms as the Perl 5 programming language system itself. |
| 212 |
|