Debian Codegraph @

README

raw
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