1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
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.
|
