1Package::Pkg(3)       User Contributed Perl Documentation      Package::Pkg(3)
2
3
4

NAME

6       Package::Pkg - Handy package munging utilities
7

VERSION

9       version 0.0020
10

SYNOPSIS

12       First, import a new keyword: "pkg"
13
14           use Package::Pkg;
15
16       Package name formation:
17
18           pkg->name( 'Xy', 'A' ) # Xy::A
19           pkg->name( $object, qw/ Cfg / ); # (ref $object)::Cfg
20
21       Subroutine installation:
22
23           pkg->install( sub { ... } => 'MyPackage::myfunction' );
24
25           # myfunction in MyPackage is now useable
26           MyPackage->myfunction( ... );
27
28       Subroutine exporting:
29
30           package MyPackage;
31
32           use Package::Pkg;
33
34           sub this { ... }
35
36           # Setup an exporter (literally sub import { ... }) for
37           # MyPackage, exporting 'this' and 'that'
38           pkg->export( that => sub { ... }, 'this' );
39
40           package main;
41
42           use MyPackage;
43
44           this( ... );
45
46           that( ... );
47

DESCRIPTION

49       Package::Pkg is a collection of useful, miscellaneous package-munging
50       utilities. Functionality is accessed via the imported "pkg" keyword,
51       although you can also invoke functions directly from the package
52       ("Package::Pkg")
53

USAGE

55   pkg->install( ... )
56       Install a subroutine, similar to Sub::Install
57
58       This method takes a number of parameters and also has a two- and three-
59       argument form (see below)
60
61           # Install an anonymous subroutine as Banana::magic
62           pkg->install( code => sub { ... } , as => 'Banana::magic' )
63           pkg->install( code => sub { ... } , into => 'Banana::magic' ) # Bzzzt! Throws an error!
64
65           # Install the subroutine Apple::xyzzy as Banana::magic
66           pkg->install( code => 'Apple::xyzzy', as => 'Banana::magic' )
67           pkg->install( code => 'Apple::xyzzy', into => 'Banana', as => 'magic' )
68           pkg->install( from => 'Apple', code => 'xyzzy', as => 'Banana::magic' )
69           pkg->install( from => 'Apple', code => 'xyzzy', into => 'Banana', as => 'magic' )
70
71           # Install the subroutine Apple::xyzzy as Banana::xyzzy
72           pkg->install( code => 'Apple::xyzzy', as => 'Banana::xyzzy' )
73           pkg->install( code => 'Apple::xyzzy', into => 'Banana' )
74           pkg->install( from => 'Apple', code => 'xyzzy', as => 'Banana::xyzzy' )
75           pkg->install( from => 'Apple', code => 'xyzzy', into => 'Banana' )
76
77       With implicit "from" (via "caller()")
78
79           package Apple;
80
81           sub xyzzy { ... }
82
83           # Install the subroutine Apple::xyzzy as Banana::xyzzy
84           pkg->install( code => 'xyzzy', as => 'Banana::xyzzy' ) # 'from' is implicitly 'Apple'
85           pkg->install( code => \&xyzzy, as => 'Banana::xyzzy' )
86
87       Acceptable parameters are:
88
89           code            A subroutine reference,
90                           A package-with-name identifier, or
91                           The name of a subroutine in the calling package
92
93           from (optional) A package identifier
94                           If :code is an identifier, then :from is the package where
95                           the subroutine can be found
96                           If :code is an identifier and :from is not given, then :from
97                           is assumed to be the calling package (via caller())
98
99           as              The name of the subroutine to install as. Can be a simple name
100                           (when paired with :into) or a full package-with-name
101
102           into (optional) A package identifier
103                           If :as is given, then the full name of the installed
104                           subroutine is (:into)::(:as)
105
106                           If :as is not given and we can derive a simple name from
107                           :code (It is a package-with-name identifier), then :as will be
108                           the name identifier part of :code
109
110   pkg->install( $code => $as )
111       This is the two-argument form of subroutine installation
112
113       Install $code subroutine as $as
114
115           pkg->install( sub { ... } => 'Banana::xyzzy' )
116
117           pkg->install( 'Scalar::Util::blessed' => 'Banana::xyzzy' )
118
119           pkg->install( 'Scalar::Util::blessed' => 'Banana::' )
120
121           pkg->install( sub { ... } => 'Banana::' ) # Bzzzt! Throws an error!
122
123       $code should be:
124
125       ·   A CODE reference
126
127               sub { ... }
128
129       ·   A package-with-name identifier
130
131               Scalar::Util::blessed
132
133       ·   The name of a subroutine in the calling package
134
135               sub xyzzy { ... }
136
137               pkg->install( 'xyzzy' => ... )
138
139       $as should be:
140
141       ·   A package-with-name identifier
142
143               Acme::Xyzzy::magic
144
145       ·   A package identifier (with a trailing ::)
146
147               Acme::Xyzzy::
148
149   pkg->install( $code => $into, $as )
150       This is the three-argument form of subroutine installation
151
152           pkg->install( sub { ... } => 'Banana', 'xyzzy' )
153
154           pkg->install( sub { ... } => 'Banana::', 'xyzzy' )
155
156           pkg->install( 'Scalar::Util::blessed' => 'Banana', 'xyzzy' )
157
158           pkg->install( 'Scalar::Util::blessed' => 'Banana::', 'xyzzy' )
159
160       $code can be the same as the two argument form
161
162       $into should be:
163
164       ·   A package identifier (trailing :: is optional)
165
166               Acme::Xyzzy::
167
168               Acme::Xyzzy
169
170       $as should be:
171
172       ·   A name (the name of the subroutine)
173
174               xyzzy
175
176               magic
177
178   $package = pkg->name( $part, [ $part, ..., $part ] )
179       Return a namespace composed by joining each $part with "::"
180
181       Superfluous/redundant "::" are automatically cleaned up and stripped
182       from the resulting $package
183
184       If the first part leads with a "::", the the calling package will be
185       prepended to $package
186
187           pkg->name( 'Xy', 'A::', '::B' )      # Xy::A::B
188           pkg->name( 'Xy', 'A::' )             # Xy::A::
189
190           {
191               package Zy;
192
193               pkg->name( '::', 'A::', '::B' )  # Zy::A::B
194               pkg->name( '::Xy::A::B' )        # Zy::Xy::A::B
195           }
196
197       In addition, if any part is blessed, "name" will resolve that part to
198       the package that the part makes reference to:
199
200           my $object = bless {}, 'Xyzzy';
201           pkg->name( $object, qw/ Cfg / );     # Xyzzy::Cfg
202

SEE ALSO

204       Sub::Install
205
206       Sub::Exporter
207

AUTHOR

209       Robert Krimen <robertkrimen@gmail.com>
210

212       This software is copyright (c) 2012 by Robert Krimen.
213
214       This is free software; you can redistribute it and/or modify it under
215       the same terms as the Perl 5 programming language system itself.
216
217
218
219perl v5.32.0                      2020-07-28                   Package::Pkg(3)
Impressum