| 1 | 16 | ▶ | use v5.12.0; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 2 | 16 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 3 | package Sub::Exporter 0.992; | ||||||||||||||||||||||||||||
| 4 | # ABSTRACT: a sophisticated exporter for custom-built routines | ||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||
| 6 | 16 | ▶ | use Carp (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 7 | 16 | ▶ | use Data::OptList 0.100 (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 8 | 16 | ▶ | use Params::SomeUtil 0.14 (); # _CODELIKE | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 9 | 16 | ▶ | use Sub::Install 0.92 (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||||||
| 11 | #pod =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 12 | #pod | ||||||||||||||||||||||||||||
| 13 | #pod Sub::Exporter must be used in two places. First, in an exporting module: | ||||||||||||||||||||||||||||
| 14 | #pod | ||||||||||||||||||||||||||||
| 15 | #pod # in the exporting module: | ||||||||||||||||||||||||||||
| 16 | #pod package Text::Tweaker; | ||||||||||||||||||||||||||||
| 17 | #pod use Sub::Exporter -setup => { | ||||||||||||||||||||||||||||
| 18 | #pod exports => [ | ||||||||||||||||||||||||||||
| 19 | #pod qw(squish titlecase), # always works the same way | ||||||||||||||||||||||||||||
| 20 | #pod reformat => \&build_reformatter, # generator to build exported function | ||||||||||||||||||||||||||||
| 21 | #pod trim => \&build_trimmer, | ||||||||||||||||||||||||||||
| 22 | #pod indent => \&build_indenter, | ||||||||||||||||||||||||||||
| 23 | #pod ], | ||||||||||||||||||||||||||||
| 24 | #pod collectors => [ 'defaults' ], | ||||||||||||||||||||||||||||
| 25 | #pod }; | ||||||||||||||||||||||||||||
| 26 | #pod | ||||||||||||||||||||||||||||
| 27 | #pod Then, in an importing module: | ||||||||||||||||||||||||||||
| 28 | #pod | ||||||||||||||||||||||||||||
| 29 | #pod # in the importing module: | ||||||||||||||||||||||||||||
| 30 | #pod use Text::Tweaker | ||||||||||||||||||||||||||||
| 31 | #pod 'squish', | ||||||||||||||||||||||||||||
| 32 | #pod indent => { margin => 5 }, | ||||||||||||||||||||||||||||
| 33 | #pod reformat => { width => 79, justify => 'full', -as => 'prettify_text' }, | ||||||||||||||||||||||||||||
| 34 | #pod defaults => { eol => 'CRLF' }; | ||||||||||||||||||||||||||||
| 35 | #pod | ||||||||||||||||||||||||||||
| 36 | #pod With this setup, the importing module ends up with three routines: C<squish>, | ||||||||||||||||||||||||||||
| 37 | #pod C<indent>, and C<prettify_text>. The latter two have been built to the | ||||||||||||||||||||||||||||
| 38 | #pod specifications of the importer -- they are not just copies of the code in the | ||||||||||||||||||||||||||||
| 39 | #pod exporting package. | ||||||||||||||||||||||||||||
| 40 | #pod | ||||||||||||||||||||||||||||
| 41 | #pod =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 42 | #pod | ||||||||||||||||||||||||||||
| 43 | #pod B<ACHTUNG!> If you're not familiar with Exporter or exporting, read | ||||||||||||||||||||||||||||
| 44 | #pod L<Sub::Exporter::Tutorial> first! | ||||||||||||||||||||||||||||
| 45 | #pod | ||||||||||||||||||||||||||||
| 46 | #pod =head2 Why Generators? | ||||||||||||||||||||||||||||
| 47 | #pod | ||||||||||||||||||||||||||||
| 48 | #pod The biggest benefit of Sub::Exporter over existing exporters (including the | ||||||||||||||||||||||||||||
| 49 | #pod ubiquitous Exporter.pm) is its ability to build new coderefs for export, rather | ||||||||||||||||||||||||||||
| 50 | #pod than to simply export code identical to that found in the exporting package. | ||||||||||||||||||||||||||||
| 51 | #pod | ||||||||||||||||||||||||||||
| 52 | #pod If your module's consumers get a routine that works like this: | ||||||||||||||||||||||||||||
| 53 | #pod | ||||||||||||||||||||||||||||
| 54 | #pod use Data::Analyze qw(analyze); | ||||||||||||||||||||||||||||
| 55 | #pod my $value = analyze($data, $tolerance, $passes); | ||||||||||||||||||||||||||||
| 56 | #pod | ||||||||||||||||||||||||||||
| 57 | #pod and they constantly pass only one or two different set of values for the | ||||||||||||||||||||||||||||
| 58 | #pod non-C<$data> arguments, your code can benefit from Sub::Exporter. By writing a | ||||||||||||||||||||||||||||
| 59 | #pod simple generator, you can let them do this, instead: | ||||||||||||||||||||||||||||
| 60 | #pod | ||||||||||||||||||||||||||||
| 61 | #pod use Data::Analyze | ||||||||||||||||||||||||||||
| 62 | #pod analyze => { tolerance => 0.10, passes => 10, -as => analyze10 }, | ||||||||||||||||||||||||||||
| 63 | #pod analyze => { tolerance => 0.15, passes => 50, -as => analyze50 }; | ||||||||||||||||||||||||||||
| 64 | #pod | ||||||||||||||||||||||||||||
| 65 | #pod my $value = analyze10($data); | ||||||||||||||||||||||||||||
| 66 | #pod | ||||||||||||||||||||||||||||
| 67 | #pod The package with the generator for that would look something like this: | ||||||||||||||||||||||||||||
| 68 | #pod | ||||||||||||||||||||||||||||
| 69 | #pod package Data::Analyze; | ||||||||||||||||||||||||||||
| 70 | #pod use Sub::Exporter -setup => { | ||||||||||||||||||||||||||||
| 71 | #pod exports => [ | ||||||||||||||||||||||||||||
| 72 | #pod analyze => \&build_analyzer, | ||||||||||||||||||||||||||||
| 73 | #pod ], | ||||||||||||||||||||||||||||
| 74 | #pod }; | ||||||||||||||||||||||||||||
| 75 | #pod | ||||||||||||||||||||||||||||
| 76 | #pod sub build_analyzer { | ||||||||||||||||||||||||||||
| 77 | #pod my ($class, $name, $arg) = @_; | ||||||||||||||||||||||||||||
| 78 | #pod | ||||||||||||||||||||||||||||
| 79 | #pod return sub { | ||||||||||||||||||||||||||||
| 80 | #pod my $data = shift; | ||||||||||||||||||||||||||||
| 81 | #pod my $tolerance = shift || $arg->{tolerance}; | ||||||||||||||||||||||||||||
| 82 | #pod my $passes = shift || $arg->{passes}; | ||||||||||||||||||||||||||||
| 83 | #pod | ||||||||||||||||||||||||||||
| 84 | #pod analyze($data, $tolerance, $passes); | ||||||||||||||||||||||||||||
| 85 | #pod } | ||||||||||||||||||||||||||||
| 86 | #pod } | ||||||||||||||||||||||||||||
| 87 | #pod | ||||||||||||||||||||||||||||
| 88 | #pod Your module's user now has to do less work to benefit from it -- and remember, | ||||||||||||||||||||||||||||
| 89 | #pod you're often your own user! Investing in customized subroutines is an | ||||||||||||||||||||||||||||
| 90 | #pod investment in future laziness. | ||||||||||||||||||||||||||||
| 91 | #pod | ||||||||||||||||||||||||||||
| 92 | #pod This also avoids a common form of ugliness seen in many modules: package-level | ||||||||||||||||||||||||||||
| 93 | #pod configuration. That is, you might have seen something like the above | ||||||||||||||||||||||||||||
| 94 | #pod implemented like so: | ||||||||||||||||||||||||||||
| 95 | #pod | ||||||||||||||||||||||||||||
| 96 | #pod use Data::Analyze qw(analyze); | ||||||||||||||||||||||||||||
| 97 | #pod $Data::Analyze::default_tolerance = 0.10; | ||||||||||||||||||||||||||||
| 98 | #pod $Data::Analyze::default_passes = 10; | ||||||||||||||||||||||||||||
| 99 | #pod | ||||||||||||||||||||||||||||
| 100 | #pod This might save time, until you have multiple modules using Data::Analyze. | ||||||||||||||||||||||||||||
| 101 | #pod Because there is only one global configuration, they step on each other's toes | ||||||||||||||||||||||||||||
| 102 | #pod and your code begins to have mysterious errors. | ||||||||||||||||||||||||||||
| 103 | #pod | ||||||||||||||||||||||||||||
| 104 | #pod Generators can also allow you to export class methods to be called as | ||||||||||||||||||||||||||||
| 105 | #pod subroutines: | ||||||||||||||||||||||||||||
| 106 | #pod | ||||||||||||||||||||||||||||
| 107 | #pod package Data::Methodical; | ||||||||||||||||||||||||||||
| 108 | #pod use Sub::Exporter -setup => { exports => { some_method => \&_curry_class } }; | ||||||||||||||||||||||||||||
| 109 | #pod | ||||||||||||||||||||||||||||
| 110 | #pod sub _curry_class { | ||||||||||||||||||||||||||||
| 111 | #pod my ($class, $name) = @_; | ||||||||||||||||||||||||||||
| 112 | #pod sub { $class->$name(@_); }; | ||||||||||||||||||||||||||||
| 113 | #pod } | ||||||||||||||||||||||||||||
| 114 | #pod | ||||||||||||||||||||||||||||
| 115 | #pod Because of the way that exporters and Sub::Exporter work, any package that | ||||||||||||||||||||||||||||
| 116 | #pod inherits from Data::Methodical can inherit its exporter and override its | ||||||||||||||||||||||||||||
| 117 | #pod C<some_method>. If a user imports C<some_method> from that package, he'll | ||||||||||||||||||||||||||||
| 118 | #pod receive a subroutine that calls the method on the subclass, rather than on | ||||||||||||||||||||||||||||
| 119 | #pod Data::Methodical itself. Keep in mind that if you re-setup Sub::Exporter in a | ||||||||||||||||||||||||||||
| 120 | #pod package that inherits from Data::Methodical you will, of course, be entirely | ||||||||||||||||||||||||||||
| 121 | #pod replacing the exporter from Data::Methodical. C<import> is a method, and is | ||||||||||||||||||||||||||||
| 122 | #pod hidden by the same means as any other method. | ||||||||||||||||||||||||||||
| 123 | #pod | ||||||||||||||||||||||||||||
| 124 | #pod =head2 Other Customizations | ||||||||||||||||||||||||||||
| 125 | #pod | ||||||||||||||||||||||||||||
| 126 | #pod Building custom routines with generators isn't the only way that Sub::Exporters | ||||||||||||||||||||||||||||
| 127 | #pod allows the importing code to refine its use of the exported routines. They may | ||||||||||||||||||||||||||||
| 128 | #pod also be renamed to avoid naming collisions. | ||||||||||||||||||||||||||||
| 129 | #pod | ||||||||||||||||||||||||||||
| 130 | #pod Consider the following code: | ||||||||||||||||||||||||||||
| 131 | #pod | ||||||||||||||||||||||||||||
| 132 | #pod # this program determines to which circle of Hell you will be condemned | ||||||||||||||||||||||||||||
| 133 | #pod use Morality qw(sin virtue); # for calculating viciousness | ||||||||||||||||||||||||||||
| 134 | #pod use Math::Trig qw(:all); # for dealing with circles | ||||||||||||||||||||||||||||
| 135 | #pod | ||||||||||||||||||||||||||||
| 136 | #pod The programmer has inadvertently imported two C<sin> routines. The solution, | ||||||||||||||||||||||||||||
| 137 | #pod in Exporter.pm-based modules, would be to import only one and then call the | ||||||||||||||||||||||||||||
| 138 | #pod other by its fully-qualified name. Alternately, the importer could write a | ||||||||||||||||||||||||||||
| 139 | #pod routine that did so, or could mess about with typeglobs. | ||||||||||||||||||||||||||||
| 140 | #pod | ||||||||||||||||||||||||||||
| 141 | #pod How much easier to write: | ||||||||||||||||||||||||||||
| 142 | #pod | ||||||||||||||||||||||||||||
| 143 | #pod # this program determines to which circle of Hell you will be condemned | ||||||||||||||||||||||||||||
| 144 | #pod use Morality qw(virtue), sin => { -as => 'offense' }; | ||||||||||||||||||||||||||||
| 145 | #pod use Math::Trig -all => { -prefix => 'trig_' }; | ||||||||||||||||||||||||||||
| 146 | #pod | ||||||||||||||||||||||||||||
| 147 | #pod and to have at one's disposal C<offense> and C<trig_sin> -- not to mention | ||||||||||||||||||||||||||||
| 148 | #pod C<trig_cos> and C<trig_tan>. | ||||||||||||||||||||||||||||
| 149 | #pod | ||||||||||||||||||||||||||||
| 150 | #pod =head1 EXPORTER CONFIGURATION | ||||||||||||||||||||||||||||
| 151 | #pod | ||||||||||||||||||||||||||||
| 152 | #pod You can configure an exporter for your package by using Sub::Exporter like so: | ||||||||||||||||||||||||||||
| 153 | #pod | ||||||||||||||||||||||||||||
| 154 | #pod package Tools; | ||||||||||||||||||||||||||||
| 155 | #pod use Sub::Exporter | ||||||||||||||||||||||||||||
| 156 | #pod -setup => { exports => [ qw(function1 function2 function3) ] }; | ||||||||||||||||||||||||||||
| 157 | #pod | ||||||||||||||||||||||||||||
| 158 | #pod This is the simplest way to use the exporter, and is basically equivalent to | ||||||||||||||||||||||||||||
| 159 | #pod this: | ||||||||||||||||||||||||||||
| 160 | #pod | ||||||||||||||||||||||||||||
| 161 | #pod package Tools; | ||||||||||||||||||||||||||||
| 162 | #pod use base qw(Exporter); | ||||||||||||||||||||||||||||
| 163 | #pod our @EXPORT_OK = qw(function1 function2 function3); | ||||||||||||||||||||||||||||
| 164 | #pod | ||||||||||||||||||||||||||||
| 165 | #pod Any basic use of Sub::Exporter will look like this: | ||||||||||||||||||||||||||||
| 166 | #pod | ||||||||||||||||||||||||||||
| 167 | #pod package Tools; | ||||||||||||||||||||||||||||
| 168 | #pod use Sub::Exporter -setup => \%config; | ||||||||||||||||||||||||||||
| 169 | #pod | ||||||||||||||||||||||||||||
| 170 | #pod The following keys are valid in C<%config>: | ||||||||||||||||||||||||||||
| 171 | #pod | ||||||||||||||||||||||||||||
| 172 | #pod exports - a list of routines to provide for exporting; each routine may be | ||||||||||||||||||||||||||||
| 173 | #pod followed by generator | ||||||||||||||||||||||||||||
| 174 | #pod groups - a list of groups to provide for exporting; each must be followed by | ||||||||||||||||||||||||||||
| 175 | #pod either (a) a list of exports, possibly with arguments for each | ||||||||||||||||||||||||||||
| 176 | #pod export, or (b) a generator | ||||||||||||||||||||||||||||
| 177 | #pod | ||||||||||||||||||||||||||||
| 178 | #pod collectors - a list of names into which values are collected for use in | ||||||||||||||||||||||||||||
| 179 | #pod routine generation; each name may be followed by a validator | ||||||||||||||||||||||||||||
| 180 | #pod | ||||||||||||||||||||||||||||
| 181 | #pod In addition to the basic options above, a few more advanced options may be | ||||||||||||||||||||||||||||
| 182 | #pod passed: | ||||||||||||||||||||||||||||
| 183 | #pod | ||||||||||||||||||||||||||||
| 184 | #pod into_level - how far up the caller stack to look for a target (default 0) | ||||||||||||||||||||||||||||
| 185 | #pod into - an explicit target (package) into which to export routines | ||||||||||||||||||||||||||||
| 186 | #pod | ||||||||||||||||||||||||||||
| 187 | #pod In other words: Sub::Exporter installs a C<import> routine which, when called, | ||||||||||||||||||||||||||||
| 188 | #pod exports routines to the calling namespace. The C<into> and C<into_level> | ||||||||||||||||||||||||||||
| 189 | #pod options change where those exported routines are installed. | ||||||||||||||||||||||||||||
| 190 | #pod | ||||||||||||||||||||||||||||
| 191 | #pod generator - a callback used to produce the code that will be installed | ||||||||||||||||||||||||||||
| 192 | #pod default: Sub::Exporter::default_generator | ||||||||||||||||||||||||||||
| 193 | #pod | ||||||||||||||||||||||||||||
| 194 | #pod installer - a callback used to install the code produced by the generator | ||||||||||||||||||||||||||||
| 195 | #pod default: Sub::Exporter::default_installer | ||||||||||||||||||||||||||||
| 196 | #pod | ||||||||||||||||||||||||||||
| 197 | #pod For information on how these callbacks are used, see the documentation for | ||||||||||||||||||||||||||||
| 198 | #pod C<L</default_generator>> and C<L</default_installer>>. | ||||||||||||||||||||||||||||
| 199 | #pod | ||||||||||||||||||||||||||||
| 200 | #pod =head2 Export Configuration | ||||||||||||||||||||||||||||
| 201 | #pod | ||||||||||||||||||||||||||||
| 202 | #pod The C<exports> list may be provided as an array reference or a hash reference. | ||||||||||||||||||||||||||||
| 203 | #pod The list is processed in such a way that the following are equivalent: | ||||||||||||||||||||||||||||
| 204 | #pod | ||||||||||||||||||||||||||||
| 205 | #pod { exports => [ qw(foo bar baz), quux => \&quux_generator ] } | ||||||||||||||||||||||||||||
| 206 | #pod | ||||||||||||||||||||||||||||
| 207 | #pod { exports => | ||||||||||||||||||||||||||||
| 208 | #pod { foo => undef, bar => undef, baz => undef, quux => \&quux_generator } } | ||||||||||||||||||||||||||||
| 209 | #pod | ||||||||||||||||||||||||||||
| 210 | #pod Generators are code that return coderefs. They are called with four | ||||||||||||||||||||||||||||
| 211 | #pod parameters: | ||||||||||||||||||||||||||||
| 212 | #pod | ||||||||||||||||||||||||||||
| 213 | #pod $class - the class whose exporter has been called (the exporting class) | ||||||||||||||||||||||||||||
| 214 | #pod $name - the name of the export for which the routine is being build | ||||||||||||||||||||||||||||
| 215 | #pod \%arg - the arguments passed for this export | ||||||||||||||||||||||||||||
| 216 | #pod \%col - the collections for this import | ||||||||||||||||||||||||||||
| 217 | #pod | ||||||||||||||||||||||||||||
| 218 | #pod Given the configuration in the L</SYNOPSIS>, the following C<use> statement: | ||||||||||||||||||||||||||||
| 219 | #pod | ||||||||||||||||||||||||||||
| 220 | #pod use Text::Tweaker | ||||||||||||||||||||||||||||
| 221 | #pod reformat => { -as => 'make_narrow', width => 33 }, | ||||||||||||||||||||||||||||
| 222 | #pod defaults => { eol => 'CR' }; | ||||||||||||||||||||||||||||
| 223 | #pod | ||||||||||||||||||||||||||||
| 224 | #pod would result in the following call to C<&build_reformatter>: | ||||||||||||||||||||||||||||
| 225 | #pod | ||||||||||||||||||||||||||||
| 226 | #pod my $code = build_reformatter( | ||||||||||||||||||||||||||||
| 227 | #pod 'Text::Tweaker', | ||||||||||||||||||||||||||||
| 228 | #pod 'reformat', | ||||||||||||||||||||||||||||
| 229 | #pod { width => 33 }, # note that -as is not passed in | ||||||||||||||||||||||||||||
| 230 | #pod { defaults => { eol => 'CR' } }, | ||||||||||||||||||||||||||||
| 231 | #pod ); | ||||||||||||||||||||||||||||
| 232 | #pod | ||||||||||||||||||||||||||||
| 233 | #pod The returned coderef (C<$code>) would then be installed as C<make_narrow> in the | ||||||||||||||||||||||||||||
| 234 | #pod calling package. | ||||||||||||||||||||||||||||
| 235 | #pod | ||||||||||||||||||||||||||||
| 236 | #pod Instead of providing a coderef in the configuration, a reference to a method | ||||||||||||||||||||||||||||
| 237 | #pod name may be provided. This method will then be called on the invocant of the | ||||||||||||||||||||||||||||
| 238 | #pod C<import> method. (In this case, we do not pass the C<$class> parameter, as it | ||||||||||||||||||||||||||||
| 239 | #pod would be redundant.) | ||||||||||||||||||||||||||||
| 240 | #pod | ||||||||||||||||||||||||||||
| 241 | #pod =head2 Group Configuration | ||||||||||||||||||||||||||||
| 242 | #pod | ||||||||||||||||||||||||||||
| 243 | #pod The C<groups> list can be passed in the same forms as C<exports>. Groups must | ||||||||||||||||||||||||||||
| 244 | #pod have values to be meaningful, which may either list exports that make up the | ||||||||||||||||||||||||||||
| 245 | #pod group (optionally with arguments) or may provide a way to build the group. | ||||||||||||||||||||||||||||
| 246 | #pod | ||||||||||||||||||||||||||||
| 247 | #pod The simpler case is the first: a group definition is a list of exports. Here's | ||||||||||||||||||||||||||||
| 248 | #pod the example that could go in exporter in the L</SYNOPSIS>. | ||||||||||||||||||||||||||||
| 249 | #pod | ||||||||||||||||||||||||||||
| 250 | #pod groups => { | ||||||||||||||||||||||||||||
| 251 | #pod default => [ qw(reformat) ], | ||||||||||||||||||||||||||||
| 252 | #pod shorteners => [ qw(squish trim) ], | ||||||||||||||||||||||||||||
| 253 | #pod email_safe => [ | ||||||||||||||||||||||||||||
| 254 | #pod 'indent', | ||||||||||||||||||||||||||||
| 255 | #pod reformat => { -as => 'email_format', width => 72 } | ||||||||||||||||||||||||||||
| 256 | #pod ], | ||||||||||||||||||||||||||||
| 257 | #pod }, | ||||||||||||||||||||||||||||
| 258 | #pod | ||||||||||||||||||||||||||||
| 259 | #pod Groups are imported by specifying their name prefixed be either a dash or a | ||||||||||||||||||||||||||||
| 260 | #pod colon. This line of code would import the C<shorteners> group: | ||||||||||||||||||||||||||||
| 261 | #pod | ||||||||||||||||||||||||||||
| 262 | #pod use Text::Tweaker qw(-shorteners); | ||||||||||||||||||||||||||||
| 263 | #pod | ||||||||||||||||||||||||||||
| 264 | #pod Arguments passed to a group when importing are merged into the groups options | ||||||||||||||||||||||||||||
| 265 | #pod and passed to any relevant generators. Groups can contain other groups, but | ||||||||||||||||||||||||||||
| 266 | #pod looping group structures are ignored. | ||||||||||||||||||||||||||||
| 267 | #pod | ||||||||||||||||||||||||||||
| 268 | #pod The other possible value for a group definition, a coderef, allows one | ||||||||||||||||||||||||||||
| 269 | #pod generator to build several exportable routines simultaneously. This is useful | ||||||||||||||||||||||||||||
| 270 | #pod when many routines must share enclosed lexical variables. The coderef must | ||||||||||||||||||||||||||||
| 271 | #pod return a hash reference. The keys will be used as export names and the values | ||||||||||||||||||||||||||||
| 272 | #pod are the subs that will be exported. | ||||||||||||||||||||||||||||
| 273 | #pod | ||||||||||||||||||||||||||||
| 274 | #pod This example shows a simple use of the group generator. | ||||||||||||||||||||||||||||
| 275 | #pod | ||||||||||||||||||||||||||||
| 276 | #pod package Data::Crypto; | ||||||||||||||||||||||||||||
| 277 | #pod use Sub::Exporter -setup => { groups => { cipher => \&build_cipher_group } }; | ||||||||||||||||||||||||||||
| 278 | #pod | ||||||||||||||||||||||||||||
| 279 | #pod sub build_cipher_group { | ||||||||||||||||||||||||||||
| 280 | #pod my ($class, $group, $arg) = @_; | ||||||||||||||||||||||||||||
| 281 | #pod my ($encode, $decode) = build_codec($arg->{secret}); | ||||||||||||||||||||||||||||
| 282 | #pod return { cipher => $encode, decipher => $decode }; | ||||||||||||||||||||||||||||
| 283 | #pod } | ||||||||||||||||||||||||||||
| 284 | #pod | ||||||||||||||||||||||||||||
| 285 | #pod The C<cipher> and C<decipher> routines are built in a group because they are | ||||||||||||||||||||||||||||
| 286 | #pod built together by code which encloses their secret in their environment. | ||||||||||||||||||||||||||||
| 287 | #pod | ||||||||||||||||||||||||||||
| 288 | #pod =head3 Default Groups | ||||||||||||||||||||||||||||
| 289 | #pod | ||||||||||||||||||||||||||||
| 290 | #pod If a module that uses Sub::Exporter is C<use>d with no arguments, it will try | ||||||||||||||||||||||||||||
| 291 | #pod to export the group named C<default>. If that group has not been specifically | ||||||||||||||||||||||||||||
| 292 | #pod configured, it will be empty, and nothing will happen. | ||||||||||||||||||||||||||||
| 293 | #pod | ||||||||||||||||||||||||||||
| 294 | #pod Another group is also created if not defined: C<all>. The C<all> group | ||||||||||||||||||||||||||||
| 295 | #pod contains all the exports from the exports list. | ||||||||||||||||||||||||||||
| 296 | #pod | ||||||||||||||||||||||||||||
| 297 | #pod =head2 Collector Configuration | ||||||||||||||||||||||||||||
| 298 | #pod | ||||||||||||||||||||||||||||
| 299 | #pod The C<collectors> entry in the exporter configuration gives names which, when | ||||||||||||||||||||||||||||
| 300 | #pod found in the import call, have their values collected and passed to every | ||||||||||||||||||||||||||||
| 301 | #pod generator. | ||||||||||||||||||||||||||||
| 302 | #pod | ||||||||||||||||||||||||||||
| 303 | #pod For example, the C<build_analyzer> generator that we saw above could be | ||||||||||||||||||||||||||||
| 304 | #pod rewritten as: | ||||||||||||||||||||||||||||
| 305 | #pod | ||||||||||||||||||||||||||||
| 306 | #pod sub build_analyzer { | ||||||||||||||||||||||||||||
| 307 | #pod my ($class, $name, $arg, $col) = @_; | ||||||||||||||||||||||||||||
| 308 | #pod | ||||||||||||||||||||||||||||
| 309 | #pod return sub { | ||||||||||||||||||||||||||||
| 310 | #pod my $data = shift; | ||||||||||||||||||||||||||||
| 311 | #pod my $tolerance = shift || $arg->{tolerance} || $col->{defaults}{tolerance}; | ||||||||||||||||||||||||||||
| 312 | #pod my $passes = shift || $arg->{passes} || $col->{defaults}{passes}; | ||||||||||||||||||||||||||||
| 313 | #pod | ||||||||||||||||||||||||||||
| 314 | #pod analyze($data, $tolerance, $passes); | ||||||||||||||||||||||||||||
| 315 | #pod } | ||||||||||||||||||||||||||||
| 316 | #pod } | ||||||||||||||||||||||||||||
| 317 | #pod | ||||||||||||||||||||||||||||
| 318 | #pod That would allow the importer to specify global defaults for his imports: | ||||||||||||||||||||||||||||
| 319 | #pod | ||||||||||||||||||||||||||||
| 320 | #pod use Data::Analyze | ||||||||||||||||||||||||||||
| 321 | #pod 'analyze', | ||||||||||||||||||||||||||||
| 322 | #pod analyze => { tolerance => 0.10, -as => analyze10 }, | ||||||||||||||||||||||||||||
| 323 | #pod analyze => { tolerance => 0.15, passes => 50, -as => analyze50 }, | ||||||||||||||||||||||||||||
| 324 | #pod defaults => { passes => 10 }; | ||||||||||||||||||||||||||||
| 325 | #pod | ||||||||||||||||||||||||||||
| 326 | #pod my $A = analyze10($data); # equivalent to analyze($data, 0.10, 10); | ||||||||||||||||||||||||||||
| 327 | #pod my $C = analyze50($data); # equivalent to analyze($data, 0.15, 50); | ||||||||||||||||||||||||||||
| 328 | #pod my $B = analyze($data, 0.20); # equivalent to analyze($data, 0.20, 10); | ||||||||||||||||||||||||||||
| 329 | #pod | ||||||||||||||||||||||||||||
| 330 | #pod If values are provided in the C<collectors> list during exporter setup, they | ||||||||||||||||||||||||||||
| 331 | #pod must be code references, and are used to validate the importer's values. The | ||||||||||||||||||||||||||||
| 332 | #pod validator is called when the collection is found, and if it returns false, an | ||||||||||||||||||||||||||||
| 333 | #pod exception is thrown. We could ensure that no one tries to set a global data | ||||||||||||||||||||||||||||
| 334 | #pod default easily: | ||||||||||||||||||||||||||||
| 335 | #pod | ||||||||||||||||||||||||||||
| 336 | #pod collectors => { defaults => sub { return (exists $_[0]->{data}) ? 0 : 1 } } | ||||||||||||||||||||||||||||
| 337 | #pod | ||||||||||||||||||||||||||||
| 338 | #pod Collector coderefs can also be used as hooks to perform arbitrary actions | ||||||||||||||||||||||||||||
| 339 | #pod before anything is exported. | ||||||||||||||||||||||||||||
| 340 | #pod | ||||||||||||||||||||||||||||
| 341 | #pod When the coderef is called, it is passed the value of the collection and a | ||||||||||||||||||||||||||||
| 342 | #pod hashref containing the following entries: | ||||||||||||||||||||||||||||
| 343 | #pod | ||||||||||||||||||||||||||||
| 344 | #pod name - the name of the collector | ||||||||||||||||||||||||||||
| 345 | #pod config - the exporter configuration (hashref) | ||||||||||||||||||||||||||||
| 346 | #pod import_args - the arguments passed to the exporter, sans collections (aref) | ||||||||||||||||||||||||||||
| 347 | #pod class - the package on which the importer was called | ||||||||||||||||||||||||||||
| 348 | #pod into - the package into which exports will be exported | ||||||||||||||||||||||||||||
| 349 | #pod | ||||||||||||||||||||||||||||
| 350 | #pod Collectors with all-caps names (that is, made up of underscore or capital A | ||||||||||||||||||||||||||||
| 351 | #pod through Z) are reserved for special use. The only currently implemented | ||||||||||||||||||||||||||||
| 352 | #pod special collector is C<INIT>, whose hook (if present in the exporter | ||||||||||||||||||||||||||||
| 353 | #pod configuration) is always run before any other hook. | ||||||||||||||||||||||||||||
| 354 | #pod | ||||||||||||||||||||||||||||
| 355 | #pod =head1 CALLING THE EXPORTER | ||||||||||||||||||||||||||||
| 356 | #pod | ||||||||||||||||||||||||||||
| 357 | #pod Arguments to the exporter (that is, the arguments after the module name in a | ||||||||||||||||||||||||||||
| 358 | #pod C<use> statement) are parsed as follows: | ||||||||||||||||||||||||||||
| 359 | #pod | ||||||||||||||||||||||||||||
| 360 | #pod First, the collectors gather any collections found in the arguments. Any | ||||||||||||||||||||||||||||
| 361 | #pod reference type may be given as the value for a collector. For each collection | ||||||||||||||||||||||||||||
| 362 | #pod given in the arguments, its validator (if any) is called. | ||||||||||||||||||||||||||||
| 363 | #pod | ||||||||||||||||||||||||||||
| 364 | #pod Next, groups are expanded. If the group is implemented by a group generator, | ||||||||||||||||||||||||||||
| 365 | #pod the generator is called. There are two special arguments which, if given to a | ||||||||||||||||||||||||||||
| 366 | #pod group, have special meaning: | ||||||||||||||||||||||||||||
| 367 | #pod | ||||||||||||||||||||||||||||
| 368 | #pod -prefix - a string to prepend to any export imported from this group | ||||||||||||||||||||||||||||
| 369 | #pod -suffix - a string to append to any export imported from this group | ||||||||||||||||||||||||||||
| 370 | #pod | ||||||||||||||||||||||||||||
| 371 | #pod Finally, individual export generators are called and all subs, generated or | ||||||||||||||||||||||||||||
| 372 | #pod otherwise, are installed in the calling package. There is only one special | ||||||||||||||||||||||||||||
| 373 | #pod argument for export generators: | ||||||||||||||||||||||||||||
| 374 | #pod | ||||||||||||||||||||||||||||
| 375 | #pod -as - where to install the exported sub | ||||||||||||||||||||||||||||
| 376 | #pod | ||||||||||||||||||||||||||||
| 377 | #pod Normally, C<-as> will contain an alternate name for the routine. It may, | ||||||||||||||||||||||||||||
| 378 | #pod however, contain a reference to a scalar. If that is the case, a reference the | ||||||||||||||||||||||||||||
| 379 | #pod generated routine will be placed in the scalar referenced by C<-as>. It will | ||||||||||||||||||||||||||||
| 380 | #pod not be installed into the calling package. | ||||||||||||||||||||||||||||
| 381 | #pod | ||||||||||||||||||||||||||||
| 382 | #pod =head2 Special Exporter Arguments | ||||||||||||||||||||||||||||
| 383 | #pod | ||||||||||||||||||||||||||||
| 384 | #pod The generated exporter accept some special options, which may be passed as the | ||||||||||||||||||||||||||||
| 385 | #pod first argument, in a hashref. | ||||||||||||||||||||||||||||
| 386 | #pod | ||||||||||||||||||||||||||||
| 387 | #pod These options are: | ||||||||||||||||||||||||||||
| 388 | #pod | ||||||||||||||||||||||||||||
| 389 | #pod into_level | ||||||||||||||||||||||||||||
| 390 | #pod into | ||||||||||||||||||||||||||||
| 391 | #pod generator | ||||||||||||||||||||||||||||
| 392 | #pod installer | ||||||||||||||||||||||||||||
| 393 | #pod | ||||||||||||||||||||||||||||
| 394 | #pod These override the same-named configuration options described in L</EXPORTER | ||||||||||||||||||||||||||||
| 395 | #pod CONFIGURATION>. | ||||||||||||||||||||||||||||
| 396 | #pod | ||||||||||||||||||||||||||||
| 397 | #pod =cut | ||||||||||||||||||||||||||||
| 398 | |||||||||||||||||||||||||||||
| 399 | # Given a potential import name, this returns the group name -- if it's got a | ||||||||||||||||||||||||||||
| 400 | # group prefix. | ||||||||||||||||||||||||||||
| 401 | 508 | ▶ | sub _group_name { | ||||||||||||||||||||||||||
|
Subroutine
_group_name: called CC=2 SCAR=6.9
| |||||||||||||||||||||||||||||
| 402 | 508 | my ($name) = @_; | |||||||||||||||||||||||||||
| 403 | |||||||||||||||||||||||||||||
| 404 | 508 | ▶ | return if (index q{-:}, (substr $name, 0, 1)) == -1; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 405 | 286 | return substr $name, 1; | |||||||||||||||||||||||||||
| 406 | } | ||||||||||||||||||||||||||||
| 407 | |||||||||||||||||||||||||||||
| 408 | # \@groups is a canonicalized opt list of exports and groups this returns | ||||||||||||||||||||||||||||
| 409 | # another canonicalized opt list with groups replaced with relevant exports. | ||||||||||||||||||||||||||||
| 410 | # \%seen is groups we've already expanded and can ignore. | ||||||||||||||||||||||||||||
| 411 | # \%merge is merged options from the group we're descending through. | ||||||||||||||||||||||||||||
| 412 | 284 | ▶ | sub _expand_groups { | ||||||||||||||||||||||||||
|
Subroutine
_expand_groups: called CC=12 SCAR=24.9
| |||||||||||||||||||||||||||||
| 413 | 284 | my ($class, $config, $groups, $collection, $seen, $merge) = @_; | |||||||||||||||||||||||||||
| 414 | 284 | ▶ | $seen ||= {}; | ||||||||||||||||||||||||||
|
Condition100%2/2
$seen ||= {}
MC/DC100%1/1
$seen ||= {}
$seen
Truth table100%2/2
A
A= $seen
| |||||||||||||||||||||||||||||
| 415 | 284 | ▶ | $merge ||= {}; | ||||||||||||||||||||||||||
|
Condition100%2/2
$merge ||= {}
MC/DC100%1/1
$merge ||= {}
$merge
Truth table100%2/2
A
A= $merge
| |||||||||||||||||||||||||||||
| 416 | 284 | my @groups = @$groups; | |||||||||||||||||||||||||||
| 417 | |||||||||||||||||||||||||||||
| 418 | 284 | for my $i (reverse 0 .. $#groups) { | |||||||||||||||||||||||||||
| 419 | 351 | ▶ | if (my $group_name = _group_name($groups[$i][0])) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 420 | 129 | my $seen = { %$seen }; # faux-dynamic scoping | |||||||||||||||||||||||||||
| 421 | |||||||||||||||||||||||||||||
| 422 | 129 | splice @groups, $i, 1, | |||||||||||||||||||||||||||
| 423 | _expand_group($class, $config, $groups[$i], $collection, $seen, $merge); | ||||||||||||||||||||||||||||
| 424 | } else { | ||||||||||||||||||||||||||||
| 425 | # there's nothing to munge in this export's args | ||||||||||||||||||||||||||||
| 426 | 222 | ▶ | next unless my %merge = %$merge; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 427 | |||||||||||||||||||||||||||||
| 428 | # we have things to merge in; do so | ||||||||||||||||||||||||||||
| 429 | 72 | ▶ | my $prefix = (delete $merge{-prefix}) || ''; | ||||||||||||||||||||||||||
|
Condition100%2/2
delete $merge{'-prefix'} || ''
MC/DC100%1/1
delete $merge{'-prefix'} || ''
delete $merge{'-prefix'}
Truth table100%2/2
A
A= delete $merge{'-prefix'}
| |||||||||||||||||||||||||||||
| 430 | 72 | ▶ | my $suffix = (delete $merge{-suffix}) || ''; | ||||||||||||||||||||||||||
|
Condition100%2/2
delete $merge{'-suffix'} || ''
MC/DC100%1/1
delete $merge{'-suffix'} || ''
delete $merge{'-suffix'}
Truth table100%2/2
A
A= delete $merge{'-suffix'}
| |||||||||||||||||||||||||||||
| 431 | |||||||||||||||||||||||||||||
| 432 | 72 | ▶ | if ( | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
&Params::SomeUtil::_CODELIKE($groups[$i][1]) or &Params::SomeUtil::_SCALAR0($groups[$i][1])
MC/DC50%1/2
&Params::SomeUtil::_CODELIKE($groups[$i][1]) or &Params::SomeUtil::_SCALAR0($groups[$i][1])
&Params::SomeUtil::_CODELIKE($groups[$i][1])
&Params::SomeUtil::_SCALAR0($groups[$i][1])
Truth table66%2/3
A or B
A= &Params::SomeUtil::_CODELIKE($groups[$i][1])B= &Params::SomeUtil::_SCALAR0($groups[$i][1])
| |||||||||||||||||||||||||||||
| 433 | Params::SomeUtil::_CODELIKE($groups[$i][1]) ## no critic Private | ||||||||||||||||||||||||||||
| 434 | or | ||||||||||||||||||||||||||||
| 435 | Params::SomeUtil::_SCALAR0($groups[$i][1]) ## no critic Private | ||||||||||||||||||||||||||||
| 436 | ) { | ||||||||||||||||||||||||||||
| 437 | # this entry was build by a group generator | ||||||||||||||||||||||||||||
| 438 | 14 | $groups[$i][0] = $prefix . $groups[$i][0] . $suffix; | |||||||||||||||||||||||||||
| 439 | } else { | ||||||||||||||||||||||||||||
| 440 | my $as | ||||||||||||||||||||||||||||
| 441 | = ref $groups[$i][1]{-as} ? $groups[$i][1]{-as} | ||||||||||||||||||||||||||||
| 442 | 58 | ▶ | : $groups[$i][1]{-as} ? $prefix . $groups[$i][1]{-as} . $suffix | ||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||
| 443 | : $prefix . $groups[$i][0] . $suffix; | ||||||||||||||||||||||||||||
| 444 | |||||||||||||||||||||||||||||
| 445 | 58 | $groups[$i][1] = { %{ $groups[$i][1] }, %merge, -as => $as }; | |||||||||||||||||||||||||||
| 446 | } | ||||||||||||||||||||||||||||
| 447 | } | ||||||||||||||||||||||||||||
| 448 | } | ||||||||||||||||||||||||||||
| 449 | |||||||||||||||||||||||||||||
| 450 | 282 | return \@groups; | |||||||||||||||||||||||||||
| 451 | } | ||||||||||||||||||||||||||||
| 452 | |||||||||||||||||||||||||||||
| 453 | # \@group is a name/value pair from an opt list. | ||||||||||||||||||||||||||||
| 454 | 157 | ▶ | sub _expand_group { | ||||||||||||||||||||||||||
|
Subroutine
_expand_group: called CC=16 SCAR=27.7
| |||||||||||||||||||||||||||||
| 455 | 157 | my ($class, $config, $group, $collection, $seen, $merge) = @_; | |||||||||||||||||||||||||||
| 456 | 157 | ▶ | $merge ||= {}; | ||||||||||||||||||||||||||
|
Condition100%2/2
$merge ||= {}
MC/DC100%1/1
$merge ||= {}
$merge
Truth table100%2/2
A
A= $merge
| |||||||||||||||||||||||||||||
| 457 | |||||||||||||||||||||||||||||
| 458 | 157 | my ($group_name, $group_arg) = @$group; | |||||||||||||||||||||||||||
| 459 | 157 | $group_name = _group_name($group_name); | |||||||||||||||||||||||||||
| 460 | |||||||||||||||||||||||||||||
| 461 | Carp::croak qq(group "$group_name" is not exported by the $class module) | ||||||||||||||||||||||||||||
| 462 | 157 | ▶ | unless exists $config->{groups}{$group_name}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 463 | |||||||||||||||||||||||||||||
| 464 | 156 | ▶ | return if $seen->{$group_name}++; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 465 | |||||||||||||||||||||||||||||
| 466 | 150 | ▶ | if (ref $group_arg) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 467 | 73 | ▶ | my $prefix = (delete $merge->{-prefix}||'') . ($group_arg->{-prefix}||''); | ||||||||||||||||||||||||||
|
Condition100%4/4
delete $merge->{'-prefix'} || ''
$group_arg->{'-prefix'} || ''
MC/DC100%1/1
delete $merge->{'-prefix'} || ''
delete $merge->{'-prefix'}
MC/DC100%1/1
$group_arg->{'-prefix'} || ''
$group_arg->{'-prefix'}
Truth table100%2/2
A
A= delete $merge->{'-prefix'}
Truth table100%2/2
A
A= $group_arg->{'-prefix'}
| |||||||||||||||||||||||||||||
| 468 | 73 | ▶ | my $suffix = ($group_arg->{-suffix}||'') . (delete $merge->{-suffix}||''); | ||||||||||||||||||||||||||
|
Condition100%4/4
$group_arg->{'-suffix'} || ''
delete $merge->{'-suffix'} || ''
MC/DC100%1/1
$group_arg->{'-suffix'} || ''
$group_arg->{'-suffix'}
MC/DC100%1/1
delete $merge->{'-suffix'} || ''
delete $merge->{'-suffix'}
Truth table100%2/2
A
A= $group_arg->{'-suffix'}
Truth table100%2/2
A
A= delete $merge->{'-suffix'}
| |||||||||||||||||||||||||||||
| 469 | 73 | ▶ | $merge = { | ||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||
| 470 | %$merge, | ||||||||||||||||||||||||||||
| 471 | %$group_arg, | ||||||||||||||||||||||||||||
| 472 | ($prefix ? (-prefix => $prefix) : ()), | ||||||||||||||||||||||||||||
| 473 | ($suffix ? (-suffix => $suffix) : ()), | ||||||||||||||||||||||||||||
| 474 | }; | ||||||||||||||||||||||||||||
| 475 | } | ||||||||||||||||||||||||||||
| 476 | |||||||||||||||||||||||||||||
| 477 | 150 | my $exports = $config->{groups}{$group_name}; | |||||||||||||||||||||||||||
| 478 | |||||||||||||||||||||||||||||
| 479 | 150 | ▶ | if ( | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
&Params::SomeUtil::_CODELIKE($exports) or &Params::SomeUtil::_SCALAR0($exports)
MC/DC100%2/2
&Params::SomeUtil::_CODELIKE($exports) or &Params::SomeUtil::_SCALAR0($exports)
&Params::SomeUtil::_CODELIKE($exports)
&Params::SomeUtil::_SCALAR0($exports)
Truth table100%3/3
A or B
A= &Params::SomeUtil::_CODELIKE($exports)B= &Params::SomeUtil::_SCALAR0($exports)
| |||||||||||||||||||||||||||||
| 480 | Params::SomeUtil::_CODELIKE($exports) ## no critic Private | ||||||||||||||||||||||||||||
| 481 | or | ||||||||||||||||||||||||||||
| 482 | Params::SomeUtil::_SCALAR0($exports) ## no critic Private | ||||||||||||||||||||||||||||
| 483 | ) { | ||||||||||||||||||||||||||||
| 484 | # I'm not very happy with this code for hiding -prefix and -suffix, but | ||||||||||||||||||||||||||||
| 485 | # it's needed, and I'm not sure, offhand, how to make it better. | ||||||||||||||||||||||||||||
| 486 | # -- rjbs, 2006-12-05 | ||||||||||||||||||||||||||||
| 487 | 14 | ▶ | my $group_arg = $merge ? { %$merge } : {}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 488 | 14 | delete $group_arg->{-prefix}; | |||||||||||||||||||||||||||
| 489 | 14 | delete $group_arg->{-suffix}; | |||||||||||||||||||||||||||
| 490 | |||||||||||||||||||||||||||||
| 491 | 14 | ▶ | my $group = Params::SomeUtil::_CODELIKE($exports) ## no critic Private | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 492 | ? $exports->($class, $group_name, $group_arg, $collection) | ||||||||||||||||||||||||||||
| 493 | : $class->$$exports($group_name, $group_arg, $collection); | ||||||||||||||||||||||||||||
| 494 | |||||||||||||||||||||||||||||
| 495 | 14 | ▶ | Carp::croak qq(group generator "$group_name" did not return a hashref) | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 496 | if ref $group ne 'HASH'; | ||||||||||||||||||||||||||||
| 497 | |||||||||||||||||||||||||||||
| 498 | 13 | my $stuff = [ map { [ $_ => $group->{$_} ] } keys %$group ]; | |||||||||||||||||||||||||||
| 499 | return @{ | ||||||||||||||||||||||||||||
| 500 | 13 | _expand_groups($class, $config, $stuff, $collection, $seen, $merge) | |||||||||||||||||||||||||||
| 501 | }; | ||||||||||||||||||||||||||||
| 502 | } else { | ||||||||||||||||||||||||||||
| 503 | 136 | $exports | |||||||||||||||||||||||||||
| 504 | = Data::OptList::mkopt($exports, "$group_name exports"); | ||||||||||||||||||||||||||||
| 505 | |||||||||||||||||||||||||||||
| 506 | return @{ | ||||||||||||||||||||||||||||
| 507 | 136 | _expand_groups($class, $config, $exports, $collection, $seen, $merge) | |||||||||||||||||||||||||||
| 508 | }; | ||||||||||||||||||||||||||||
| 509 | } | ||||||||||||||||||||||||||||
| 510 | } | ||||||||||||||||||||||||||||
| 511 | |||||||||||||||||||||||||||||
| 512 | 113 | ▶ | sub _mk_collection_builder { | ||||||||||||||||||||||||||
|
Subroutine
_mk_collection_builder: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 513 | 113 | my ($col, $etc) = @_; | |||||||||||||||||||||||||||
| 514 | 113 | my ($config, $import_args, $class, $into) = @$etc; | |||||||||||||||||||||||||||
| 515 | |||||||||||||||||||||||||||||
| 516 | 113 | my %seen; | |||||||||||||||||||||||||||
| 517 | 37 | ▶ | sub { | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=6 SCAR=17.9
| |||||||||||||||||||||||||||||
| 518 | 37 | my ($collection) = @_; | |||||||||||||||||||||||||||
| 519 | 37 | my ($name, $value) = @$collection; | |||||||||||||||||||||||||||
| 520 | |||||||||||||||||||||||||||||
| 521 | Carp::croak "collection $name provided multiple times in import" | ||||||||||||||||||||||||||||
| 522 | 37 | ▶ | if $seen{ $name }++; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 523 | |||||||||||||||||||||||||||||
| 524 | 36 | ▶ | if (ref(my $hook = $config->{collectors}{$name})) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 525 | 30 | my $arg = { | |||||||||||||||||||||||||||
| 526 | name => $name, | ||||||||||||||||||||||||||||
| 527 | config => $config, | ||||||||||||||||||||||||||||
| 528 | import_args => $import_args, | ||||||||||||||||||||||||||||
| 529 | class => $class, | ||||||||||||||||||||||||||||
| 530 | into => $into, | ||||||||||||||||||||||||||||
| 531 | }; | ||||||||||||||||||||||||||||
| 532 | |||||||||||||||||||||||||||||
| 533 | 30 | my $error_msg = "collection $name failed validation"; | |||||||||||||||||||||||||||
| 534 | 30 | ▶ | if (Params::SomeUtil::_SCALAR0($hook)) { ## no critic Private | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 535 | 2 | ▶ | Carp::croak $error_msg unless $class->$$hook($value, $arg); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 536 | } else { | ||||||||||||||||||||||||||||
| 537 | 28 | ▶ | Carp::croak $error_msg unless $hook->($value, $arg); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 538 | } | ||||||||||||||||||||||||||||
| 539 | } | ||||||||||||||||||||||||||||
| 540 | |||||||||||||||||||||||||||||
| 541 | 30 | $col->{ $name } = $value; | |||||||||||||||||||||||||||
| 542 | } | ||||||||||||||||||||||||||||
| 543 | 113 | } | |||||||||||||||||||||||||||
| 544 | |||||||||||||||||||||||||||||
| 545 | # Given a config and pre-canonicalized importer args, remove collections from | ||||||||||||||||||||||||||||
| 546 | # the args and return them. | ||||||||||||||||||||||||||||
| 547 | 113 | ▶ | sub _collect_collections { | ||||||||||||||||||||||||||
|
Subroutine
_collect_collections: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||||||
| 548 | 113 | my ($config, $import_args, $class, $into) = @_; | |||||||||||||||||||||||||||
| 549 | |||||||||||||||||||||||||||||
| 550 | my @collections | ||||||||||||||||||||||||||||
| 551 | 35 | = map { splice @$import_args, $_, 1 } | |||||||||||||||||||||||||||
| 552 | 113 | grep { exists $config->{collectors}{ $import_args->[$_][0] } } | |||||||||||||||||||||||||||
| 553 | reverse 0 .. $#$import_args; | ||||||||||||||||||||||||||||
| 554 | |||||||||||||||||||||||||||||
| 555 | 113 | ▶ | unshift @collections, [ INIT => {} ] if $config->{collectors}{INIT}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 556 | |||||||||||||||||||||||||||||
| 557 | 113 | my $col = {}; | |||||||||||||||||||||||||||
| 558 | 113 | my $builder = _mk_collection_builder($col, \@_); | |||||||||||||||||||||||||||
| 559 | 113 | for my $collection (@collections) { | |||||||||||||||||||||||||||
| 560 | 37 | $builder->($collection) | |||||||||||||||||||||||||||
| 561 | } | ||||||||||||||||||||||||||||
| 562 | |||||||||||||||||||||||||||||
| 563 | 106 | return $col; | |||||||||||||||||||||||||||
| 564 | } | ||||||||||||||||||||||||||||
| 565 | |||||||||||||||||||||||||||||
| 566 | #pod =head1 SUBROUTINES | ||||||||||||||||||||||||||||
| 567 | #pod | ||||||||||||||||||||||||||||
| 568 | #pod =head2 setup_exporter | ||||||||||||||||||||||||||||
| 569 | #pod | ||||||||||||||||||||||||||||
| 570 | #pod This routine builds and installs an C<import> routine. It is called with one | ||||||||||||||||||||||||||||
| 571 | #pod argument, a hashref containing the exporter configuration. Using this, it | ||||||||||||||||||||||||||||
| 572 | #pod builds an exporter and installs it into the calling package with the name | ||||||||||||||||||||||||||||
| 573 | #pod "import." In addition to the normal exporter configuration, a few named | ||||||||||||||||||||||||||||
| 574 | #pod arguments may be passed in the hashref: | ||||||||||||||||||||||||||||
| 575 | #pod | ||||||||||||||||||||||||||||
| 576 | #pod into - into what package should the exporter be installed | ||||||||||||||||||||||||||||
| 577 | #pod into_level - into what level up the stack should the exporter be installed | ||||||||||||||||||||||||||||
| 578 | #pod as - what name should the installed exporter be given | ||||||||||||||||||||||||||||
| 579 | #pod | ||||||||||||||||||||||||||||
| 580 | #pod By default the exporter is installed with the name C<import> into the immediate | ||||||||||||||||||||||||||||
| 581 | #pod caller of C<setup_exporter>. In other words, if your package calls | ||||||||||||||||||||||||||||
| 582 | #pod C<setup_exporter> without providing any of the three above arguments, it will | ||||||||||||||||||||||||||||
| 583 | #pod have an C<import> routine installed. | ||||||||||||||||||||||||||||
| 584 | #pod | ||||||||||||||||||||||||||||
| 585 | #pod Providing both C<into> and C<into_level> will cause an exception to be thrown. | ||||||||||||||||||||||||||||
| 586 | #pod | ||||||||||||||||||||||||||||
| 587 | #pod The exporter is built by C<L</build_exporter>>. | ||||||||||||||||||||||||||||
| 588 | #pod | ||||||||||||||||||||||||||||
| 589 | #pod =cut | ||||||||||||||||||||||||||||
| 590 | |||||||||||||||||||||||||||||
| 591 | 23 | ▶ | sub setup_exporter { | ||||||||||||||||||||||||||
|
Subroutine
setup_exporter: called CC=6 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||||
| 592 | 23 | my ($config) = @_; | |||||||||||||||||||||||||||
| 593 | |||||||||||||||||||||||||||||
| 594 | Carp::croak 'into and into_level may not both be supplied to exporter' | ||||||||||||||||||||||||||||
| 595 | 23 | ▶ | if exists $config->{into} and exists $config->{into_level}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
exists $config->{"into"} and exists $config->{"into_level"}
MC/DC100%2/2
exists $config->{"into"} and exists $config->{"into_level"}
exists $config->{"into"}
exists $config->{"into_level"}
Truth table100%3/3
A and B
A= exists $config->{"into"}B= exists $config->{"into_level"}
| |||||||||||||||||||||||||||||
| 596 | |||||||||||||||||||||||||||||
| 597 | 22 | ▶ | my $as = delete $config->{as} || 'import'; | ||||||||||||||||||||||||||
|
Condition100%2/2
delete $config->{'as'} || 'import'
MC/DC100%1/1
delete $config->{'as'} || 'import'
delete $config->{'as'}
Truth table100%2/2
A
A= delete $config->{'as'}
| |||||||||||||||||||||||||||||
| 598 | my $into | ||||||||||||||||||||||||||||
| 599 | = exists $config->{into} ? delete $config->{into} | ||||||||||||||||||||||||||||
| 600 | : exists $config->{into_level} ? caller(delete $config->{into_level}) | ||||||||||||||||||||||||||||
| 601 | 22 | ▶ | : caller(0); | ||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||
| 602 | |||||||||||||||||||||||||||||
| 603 | 22 | my $import = build_exporter($config); | |||||||||||||||||||||||||||
| 604 | |||||||||||||||||||||||||||||
| 605 | 22 | Sub::Install::reinstall_sub({ | |||||||||||||||||||||||||||
| 606 | code => $import, | ||||||||||||||||||||||||||||
| 607 | into => $into, | ||||||||||||||||||||||||||||
| 608 | as => $as, | ||||||||||||||||||||||||||||
| 609 | }); | ||||||||||||||||||||||||||||
| 610 | } | ||||||||||||||||||||||||||||
| 611 | |||||||||||||||||||||||||||||
| 612 | #pod =head2 build_exporter | ||||||||||||||||||||||||||||
| 613 | #pod | ||||||||||||||||||||||||||||
| 614 | #pod Given a standard exporter configuration, this routine builds and returns an | ||||||||||||||||||||||||||||
| 615 | #pod exporter -- that is, a subroutine that can be installed as a class method to | ||||||||||||||||||||||||||||
| 616 | #pod perform exporting on request. | ||||||||||||||||||||||||||||
| 617 | #pod | ||||||||||||||||||||||||||||
| 618 | #pod Usually, this method is called by C<L</setup_exporter>>, which then installs | ||||||||||||||||||||||||||||
| 619 | #pod the exporter as a package's import routine. | ||||||||||||||||||||||||||||
| 620 | #pod | ||||||||||||||||||||||||||||
| 621 | #pod =cut | ||||||||||||||||||||||||||||
| 622 | |||||||||||||||||||||||||||||
| 623 | 51 | ▶ | sub _key_intersection { | ||||||||||||||||||||||||||
|
Subroutine
_key_intersection: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 624 | 51 | my ($x, $y) = @_; | |||||||||||||||||||||||||||
| 625 | 51 | my %seen = map { $_ => 1 } keys %$x; | |||||||||||||||||||||||||||
| 626 | 51 | my @names = grep { $seen{$_} } keys %$y; | |||||||||||||||||||||||||||
| 627 | } | ||||||||||||||||||||||||||||
| 628 | |||||||||||||||||||||||||||||
| 629 | # Given the config passed to setup_exporter, which contains sugary opt list | ||||||||||||||||||||||||||||
| 630 | # data, rewrite the opt lists into hashes, catch a few kinds of invalid | ||||||||||||||||||||||||||||
| 631 | # configurations, and set up defaults. Since the config is a reference, it's | ||||||||||||||||||||||||||||
| 632 | # rewritten in place. | ||||||||||||||||||||||||||||
| 633 | 16 | my %valid_config_key; | |||||||||||||||||||||||||||
| 634 | 16 | ▶ | BEGIN { | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 635 | %valid_config_key = | ||||||||||||||||||||||||||||
| 636 | 16 | map { $_ => 1 } | |||||||||||||||||||||||||||
| 637 | qw(as collectors installer generator exports groups into into_level), | ||||||||||||||||||||||||||||
| 638 | qw(exporter), # deprecated | ||||||||||||||||||||||||||||
| 639 | } | ||||||||||||||||||||||||||||
| 640 | |||||||||||||||||||||||||||||
| 641 | 51 | ▶ | sub _assert_collector_names_ok { | ||||||||||||||||||||||||||
|
Subroutine
_assert_collector_names_ok: called CC=3 SCAR=14.2
| |||||||||||||||||||||||||||||
| 642 | 51 | my ($collectors) = @_; | |||||||||||||||||||||||||||
| 643 | |||||||||||||||||||||||||||||
| 644 | 51 | for my $reserved_name (grep { /\A[_A-Z]+\z/ } keys %$collectors) { | |||||||||||||||||||||||||||
| 645 | 0 | ▶ | Carp::croak "unknown reserved collector name: $reserved_name" | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 646 | if $reserved_name ne 'INIT'; | ||||||||||||||||||||||||||||
| 647 | } | ||||||||||||||||||||||||||||
| 648 | } | ||||||||||||||||||||||||||||
| 649 | |||||||||||||||||||||||||||||
| 650 | 53 | ▶ | sub _rewrite_build_config { | ||||||||||||||||||||||||||
|
Subroutine
_rewrite_build_config: called CC=13 SCAR=25.8
| |||||||||||||||||||||||||||||
| 651 | 53 | my ($config) = @_; | |||||||||||||||||||||||||||
| 652 | |||||||||||||||||||||||||||||
| 653 | 53 | ▶ | if (my @keys = grep { not exists $valid_config_key{$_} } keys %$config) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 654 | 1 | Carp::croak "unknown options (@keys) passed to Sub::Exporter"; | |||||||||||||||||||||||||||
| 655 | } | ||||||||||||||||||||||||||||
| 656 | |||||||||||||||||||||||||||||
| 657 | Carp::croak q(into and into_level may not both be supplied to exporter) | ||||||||||||||||||||||||||||
| 658 | 52 | ▶ | if exists $config->{into} and exists $config->{into_level}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
exists $config->{"into"} and exists $config->{"into_level"}
MC/DC100%2/2
exists $config->{"into"} and exists $config->{"into_level"}
exists $config->{"into"}
exists $config->{"into_level"}
Truth table100%3/3
A and B
A= exists $config->{"into"}B= exists $config->{"into_level"}
| |||||||||||||||||||||||||||||
| 659 | |||||||||||||||||||||||||||||
| 660 | # XXX: Remove after deprecation period. | ||||||||||||||||||||||||||||
| 661 | 51 | ▶ | if ($config->{exporter}) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 662 | 0 | Carp::cluck "'exporter' argument to build_exporter is deprecated. Use 'installer' instead; the semantics are identical."; | |||||||||||||||||||||||||||
| 663 | 0 | $config->{installer} = delete $config->{exporter}; | |||||||||||||||||||||||||||
| 664 | } | ||||||||||||||||||||||||||||
| 665 | |||||||||||||||||||||||||||||
| 666 | Carp::croak q(into and into_level may not both be supplied to exporter) | ||||||||||||||||||||||||||||
| 667 | 51 | ▶ | if exists $config->{into} and exists $config->{into_level}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
exists $config->{"into"} and exists $config->{"into_level"}
MC/DC0%0/2
exists $config->{"into"} and exists $config->{"into_level"}
exists $config->{"into"}
exists $config->{"into_level"}
Truth table66%2/3
A and B
A= exists $config->{"into"}B= exists $config->{"into_level"}
| |||||||||||||||||||||||||||||
| 668 | |||||||||||||||||||||||||||||
| 669 | 51 | for (qw(exports collectors)) { | |||||||||||||||||||||||||||
| 670 | $config->{$_} = Data::OptList::mkopt_hash( | ||||||||||||||||||||||||||||
| 671 | 102 | $config->{$_}, | |||||||||||||||||||||||||||
| 672 | $_, | ||||||||||||||||||||||||||||
| 673 | [ 'CODE', 'SCALAR' ], | ||||||||||||||||||||||||||||
| 674 | ); | ||||||||||||||||||||||||||||
| 675 | } | ||||||||||||||||||||||||||||
| 676 | |||||||||||||||||||||||||||||
| 677 | 51 | _assert_collector_names_ok($config->{collectors}); | |||||||||||||||||||||||||||
| 678 | |||||||||||||||||||||||||||||
| 679 | 51 | ▶ | if (my @names = _key_intersection(@$config{qw(exports collectors)})) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 680 | 1 | Carp::croak "names (@names) used in both collections and exports"; | |||||||||||||||||||||||||||
| 681 | } | ||||||||||||||||||||||||||||
| 682 | |||||||||||||||||||||||||||||
| 683 | $config->{groups} = Data::OptList::mkopt_hash( | ||||||||||||||||||||||||||||
| 684 | $config->{groups}, | ||||||||||||||||||||||||||||
| 685 | 50 | 'groups', | |||||||||||||||||||||||||||
| 686 | [ | ||||||||||||||||||||||||||||
| 687 | 'HASH', # standard opt list | ||||||||||||||||||||||||||||
| 688 | 'ARRAY', # standard opt list | ||||||||||||||||||||||||||||
| 689 | 'CODE', # group generator | ||||||||||||||||||||||||||||
| 690 | 'SCALAR', # name of group generation method | ||||||||||||||||||||||||||||
| 691 | ] | ||||||||||||||||||||||||||||
| 692 | ); | ||||||||||||||||||||||||||||
| 693 | |||||||||||||||||||||||||||||
| 694 | # by default, export nothing | ||||||||||||||||||||||||||||
| 695 | 50 | ▶ | $config->{groups}{default} ||= []; | ||||||||||||||||||||||||||
|
Condition100%2/2
$config->{"groups"}{"default"} ||= []
MC/DC100%1/1
$config->{"groups"}{"default"} ||= []
$config->{"groups"}{"default"}
Truth table100%2/2
A
A= $config->{"groups"}{"default"}
| |||||||||||||||||||||||||||||
| 696 | |||||||||||||||||||||||||||||
| 697 | # by default, build an all-inclusive 'all' group | ||||||||||||||||||||||||||||
| 698 | 50 | ▶ | $config->{groups}{all} ||= [ keys %{ $config->{exports} } ]; | ||||||||||||||||||||||||||
|
Condition100%2/2
$config->{"groups"}{"all"} ||= [keys %{$$config{"exports"};}]
MC/DC100%1/1
$config->{"groups"}{"all"} ||= [keys %{$$config{"exports"};}]
$config->{"groups"}{"all"}
Truth table100%2/2
A
A= $config->{"groups"}{"all"}
| |||||||||||||||||||||||||||||
| 699 | |||||||||||||||||||||||||||||
| 700 | 50 | ▶ | $config->{generator} ||= \&default_generator; | ||||||||||||||||||||||||||
|
Condition100%2/2
$config->{"generator"} ||= \&Sub::Exporter::default_generator
MC/DC100%1/1
$config->{"generator"} ||= \&Sub::Exporter::default_generator
$config->{"generator"}
Truth table100%2/2
A
A= $config->{"generator"}
| |||||||||||||||||||||||||||||
| 701 | 50 | ▶ | $config->{installer} ||= \&default_installer; | ||||||||||||||||||||||||||
|
Condition100%2/2
$config->{"installer"} ||= \&Sub::Exporter::default_installer
MC/DC100%1/1
$config->{"installer"} ||= \&Sub::Exporter::default_installer
$config->{"installer"}
Truth table100%2/2
A
A= $config->{"installer"}
| |||||||||||||||||||||||||||||
| 702 | } | ||||||||||||||||||||||||||||
| 703 | |||||||||||||||||||||||||||||
| 704 | 53 | ▶ | sub build_exporter { | ||||||||||||||||||||||||||
|
Subroutine
build_exporter: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 705 | 53 | my ($config) = @_; | |||||||||||||||||||||||||||
| 706 | |||||||||||||||||||||||||||||
| 707 | 53 | _rewrite_build_config($config); | |||||||||||||||||||||||||||
| 708 | |||||||||||||||||||||||||||||
| 709 | 105 | ▶ | my $import = sub { | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=12 SCAR=25.1
| |||||||||||||||||||||||||||||
| 710 | 105 | my ($class) = shift; | |||||||||||||||||||||||||||
| 711 | |||||||||||||||||||||||||||||
| 712 | # XXX: clean this up -- rjbs, 2006-03-16 | ||||||||||||||||||||||||||||
| 713 | 105 | ▶ | my $special = (ref $_[0]) ? shift(@_) : {}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 714 | Carp::croak q(into and into_level may not both be supplied to exporter) | ||||||||||||||||||||||||||||
| 715 | 105 | ▶ | if exists $special->{into} and exists $special->{into_level}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
exists $special->{"into"} and exists $special->{"into_level"}
MC/DC100%2/2
exists $special->{"into"} and exists $special->{"into_level"}
exists $special->{"into"}
exists $special->{"into_level"}
Truth table100%3/3
A and B
A= exists $special->{"into"}B= exists $special->{"into_level"}
| |||||||||||||||||||||||||||||
| 716 | |||||||||||||||||||||||||||||
| 717 | 104 | ▶ | if ($special->{exporter}) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 718 | 0 | Carp::cluck "'exporter' special import argument is deprecated. Use 'installer' instead; the semantics are identical."; | |||||||||||||||||||||||||||
| 719 | 0 | $special->{installer} = delete $special->{exporter}; | |||||||||||||||||||||||||||
| 720 | } | ||||||||||||||||||||||||||||
| 721 | |||||||||||||||||||||||||||||
| 722 | my $into | ||||||||||||||||||||||||||||
| 723 | = defined $special->{into} ? delete $special->{into} | ||||||||||||||||||||||||||||
| 724 | : defined $special->{into_level} ? caller(delete $special->{into_level}) | ||||||||||||||||||||||||||||
| 725 | : defined $config->{into} ? $config->{into} | ||||||||||||||||||||||||||||
| 726 | : defined $config->{into_level} ? caller($config->{into_level}) | ||||||||||||||||||||||||||||
| 727 | 104 | ▶ | : caller(0); | ||||||||||||||||||||||||||
|
Branch: 4 branches
| |||||||||||||||||||||||||||||
| 728 | |||||||||||||||||||||||||||||
| 729 | 104 | ▶ | my $generator = delete $special->{generator} || $config->{generator}; | ||||||||||||||||||||||||||
|
Condition66%2/3
delete $special->{'generator'} || $config->{'generator'}
MC/DC0%0/2
delete $special->{'generator'} || $config->{'generator'}
delete $special->{'generator'}
$config->{'generator'}
Truth table66%2/3
A || B
A= delete $special->{'generator'}B= $config->{'generator'}
| |||||||||||||||||||||||||||||
| 730 | 104 | ▶ | my $installer = delete $special->{installer} || $config->{installer}; | ||||||||||||||||||||||||||
|
Condition66%2/3
delete $special->{'installer'} || $config->{'installer'}
MC/DC0%0/2
delete $special->{'installer'} || $config->{'installer'}
delete $special->{'installer'}
$config->{'installer'}
Truth table66%2/3
A || B
A= delete $special->{'installer'}B= $config->{'installer'}
| |||||||||||||||||||||||||||||
| 731 | |||||||||||||||||||||||||||||
| 732 | # this builds a AOA, where the inner arrays are [ name => value_ref ] | ||||||||||||||||||||||||||||
| 733 | 104 | my $import_args = Data::OptList::mkopt([ @_ ]); | |||||||||||||||||||||||||||
| 734 | |||||||||||||||||||||||||||||
| 735 | # is this right? defaults first or collectors first? -- rjbs, 2006-06-24 | ||||||||||||||||||||||||||||
| 736 | 104 | ▶ | $import_args = [ [ -default => undef ] ] unless @$import_args; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 737 | |||||||||||||||||||||||||||||
| 738 | 104 | my $collection = _collect_collections($config, $import_args, $class, $into); | |||||||||||||||||||||||||||
| 739 | |||||||||||||||||||||||||||||
| 740 | 101 | my $to_import = _expand_groups($class, $config, $import_args, $collection); | |||||||||||||||||||||||||||
| 741 | |||||||||||||||||||||||||||||
| 742 | # now, finally $import_arg is really the "to do" list | ||||||||||||||||||||||||||||
| 743 | 100 | _do_import( | |||||||||||||||||||||||||||
| 744 | { | ||||||||||||||||||||||||||||
| 745 | class => $class, | ||||||||||||||||||||||||||||
| 746 | col => $collection, | ||||||||||||||||||||||||||||
| 747 | config => $config, | ||||||||||||||||||||||||||||
| 748 | into => $into, | ||||||||||||||||||||||||||||
| 749 | generator => $generator, | ||||||||||||||||||||||||||||
| 750 | installer => $installer, | ||||||||||||||||||||||||||||
| 751 | }, | ||||||||||||||||||||||||||||
| 752 | $to_import, | ||||||||||||||||||||||||||||
| 753 | ); | ||||||||||||||||||||||||||||
| 754 | 50 | }; | |||||||||||||||||||||||||||
| 755 | |||||||||||||||||||||||||||||
| 756 | 50 | return $import; | |||||||||||||||||||||||||||
| 757 | } | ||||||||||||||||||||||||||||
| 758 | |||||||||||||||||||||||||||||
| 759 | 100 | ▶ | sub _do_import { | ||||||||||||||||||||||||||
|
Subroutine
_do_import: called CC=7 SCAR=19.5
| |||||||||||||||||||||||||||||
| 760 | 100 | my ($arg, $to_import) = @_; | |||||||||||||||||||||||||||
| 761 | |||||||||||||||||||||||||||||
| 762 | 100 | my @todo; | |||||||||||||||||||||||||||
| 763 | |||||||||||||||||||||||||||||
| 764 | 100 | for my $pair (@$to_import) { | |||||||||||||||||||||||||||
| 765 | 136 | my ($name, $import_arg) = @$pair; | |||||||||||||||||||||||||||
| 766 | |||||||||||||||||||||||||||||
| 767 | 136 | my ($generator, $as); | |||||||||||||||||||||||||||
| 768 | |||||||||||||||||||||||||||||
| 769 | 136 | ▶ | if ($import_arg and Params::SomeUtil::_CODELIKE($import_arg)) { ## no critic | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
$import_arg and &Params::SomeUtil::_CODELIKE($import_arg)
MC/DC100%2/2
$import_arg and &Params::SomeUtil::_CODELIKE($import_arg)
$import_arg
&Params::SomeUtil::_CODELIKE($import_arg)
Truth table100%3/3
A and B
A= $import_argB= &Params::SomeUtil::_CODELIKE($import_arg)
| |||||||||||||||||||||||||||||
| 770 | # This is the case when a group generator has inserted name/code pairs. | ||||||||||||||||||||||||||||
| 771 | 10 | ▶ | $generator = sub { $import_arg }; | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 772 | 10 | $as = $name; | |||||||||||||||||||||||||||
| 773 | } else { | ||||||||||||||||||||||||||||
| 774 | 126 | ▶ | $import_arg = { $import_arg ? %$import_arg : () }; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 775 | |||||||||||||||||||||||||||||
| 776 | Carp::croak qq("$name" is not exported by the $arg->{class} module) | ||||||||||||||||||||||||||||
| 777 | 126 | ▶ | unless exists $arg->{config}{exports}{$name}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 778 | |||||||||||||||||||||||||||||
| 779 | 125 | $generator = $arg->{config}{exports}{$name}; | |||||||||||||||||||||||||||
| 780 | |||||||||||||||||||||||||||||
| 781 | 125 | ▶ | $as = exists $import_arg->{-as} ? (delete $import_arg->{-as}) : $name; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 782 | } | ||||||||||||||||||||||||||||
| 783 | |||||||||||||||||||||||||||||
| 784 | my $code = $arg->{generator}->( | ||||||||||||||||||||||||||||
| 785 | { | ||||||||||||||||||||||||||||
| 786 | class => $arg->{class}, | ||||||||||||||||||||||||||||
| 787 | name => $name, | ||||||||||||||||||||||||||||
| 788 | arg => $import_arg, | ||||||||||||||||||||||||||||
| 789 | col => $arg->{col}, | ||||||||||||||||||||||||||||
| 790 | 135 | generator => $generator, | |||||||||||||||||||||||||||
| 791 | } | ||||||||||||||||||||||||||||
| 792 | ); | ||||||||||||||||||||||||||||
| 793 | |||||||||||||||||||||||||||||
| 794 | 133 | push @todo, $as, $code; | |||||||||||||||||||||||||||
| 795 | } | ||||||||||||||||||||||||||||
| 796 | |||||||||||||||||||||||||||||
| 797 | $arg->{installer}->( | ||||||||||||||||||||||||||||
| 798 | { | ||||||||||||||||||||||||||||
| 799 | class => $arg->{class}, | ||||||||||||||||||||||||||||
| 800 | into => $arg->{into}, | ||||||||||||||||||||||||||||
| 801 | col => $arg->{col}, | ||||||||||||||||||||||||||||
| 802 | }, | ||||||||||||||||||||||||||||
| 803 | 97 | \@todo, | |||||||||||||||||||||||||||
| 804 | ); | ||||||||||||||||||||||||||||
| 805 | } | ||||||||||||||||||||||||||||
| 806 | |||||||||||||||||||||||||||||
| 807 | ## Cute idea, possibly for future use: also supply an "unimport" for: | ||||||||||||||||||||||||||||
| 808 | ## no Module::Whatever qw(arg arg arg); | ||||||||||||||||||||||||||||
| 809 | # sub _unexport { | ||||||||||||||||||||||||||||
| 810 | # my (undef, undef, undef, undef, undef, $as, $into) = @_; | ||||||||||||||||||||||||||||
| 811 | # | ||||||||||||||||||||||||||||
| 812 | # if (ref $as eq 'SCALAR') { | ||||||||||||||||||||||||||||
| 813 | # undef $$as; | ||||||||||||||||||||||||||||
| 814 | # } elsif (ref $as) { | ||||||||||||||||||||||||||||
| 815 | # Carp::croak "invalid reference type for $as: " . ref $as; | ||||||||||||||||||||||||||||
| 816 | # } else { | ||||||||||||||||||||||||||||
| 817 | # no strict 'refs'; | ||||||||||||||||||||||||||||
| 818 | # delete &{$into . '::' . $as}; | ||||||||||||||||||||||||||||
| 819 | # } | ||||||||||||||||||||||||||||
| 820 | # } | ||||||||||||||||||||||||||||
| 821 | |||||||||||||||||||||||||||||
| 822 | #pod =head2 default_generator | ||||||||||||||||||||||||||||
| 823 | #pod | ||||||||||||||||||||||||||||
| 824 | #pod This is Sub::Exporter's default generator. It takes bits of configuration that | ||||||||||||||||||||||||||||
| 825 | #pod have been gathered during the import and turns them into a coderef that can be | ||||||||||||||||||||||||||||
| 826 | #pod installed. | ||||||||||||||||||||||||||||
| 827 | #pod | ||||||||||||||||||||||||||||
| 828 | #pod my $code = default_generator(\%arg); | ||||||||||||||||||||||||||||
| 829 | #pod | ||||||||||||||||||||||||||||
| 830 | #pod Passed arguments are: | ||||||||||||||||||||||||||||
| 831 | #pod | ||||||||||||||||||||||||||||
| 832 | #pod class - the class on which the import method was called | ||||||||||||||||||||||||||||
| 833 | #pod name - the name of the export being generated | ||||||||||||||||||||||||||||
| 834 | #pod arg - the arguments to the generator | ||||||||||||||||||||||||||||
| 835 | #pod col - the collections | ||||||||||||||||||||||||||||
| 836 | #pod | ||||||||||||||||||||||||||||
| 837 | #pod generator - the generator to be used to build the export (code or scalar ref) | ||||||||||||||||||||||||||||
| 838 | #pod | ||||||||||||||||||||||||||||
| 839 | #pod =cut | ||||||||||||||||||||||||||||
| 840 | |||||||||||||||||||||||||||||
| 841 | 107 | ▶ | sub default_generator { | ||||||||||||||||||||||||||
|
Subroutine
default_generator: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||||||||||||||||
| 842 | 107 | my ($arg) = @_; | |||||||||||||||||||||||||||
| 843 | 107 | my ($class, $name, $generator) = @$arg{qw(class name generator)}; | |||||||||||||||||||||||||||
| 844 | |||||||||||||||||||||||||||||
| 845 | 107 | ▶ | if (not defined $generator) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 846 | 39 | ▶ | my $code = $class->can($name) | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 847 | or Carp::croak "can't locate exported subroutine $name via $class"; | ||||||||||||||||||||||||||||
| 848 | 37 | return $code; | |||||||||||||||||||||||||||
| 849 | } | ||||||||||||||||||||||||||||
| 850 | |||||||||||||||||||||||||||||
| 851 | # I considered making this "$class->$generator(" but it seems that | ||||||||||||||||||||||||||||
| 852 | # overloading precedence would turn an overloaded-as-code generator object | ||||||||||||||||||||||||||||
| 853 | # into a string before code. -- rjbs, 2006-06-11 | ||||||||||||||||||||||||||||
| 854 | return $generator->($class, $name, $arg->{arg}, $arg->{col}) | ||||||||||||||||||||||||||||
| 855 | 68 | ▶ | if Params::SomeUtil::_CODELIKE($generator); ## no critic Private | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 856 | |||||||||||||||||||||||||||||
| 857 | # This "must" be a scalar reference, to a generator method name. | ||||||||||||||||||||||||||||
| 858 | # -- rjbs, 2006-12-05 | ||||||||||||||||||||||||||||
| 859 | 2 | return $class->$$generator($name, $arg->{arg}, $arg->{col}); | |||||||||||||||||||||||||||
| 860 | } | ||||||||||||||||||||||||||||
| 861 | |||||||||||||||||||||||||||||
| 862 | #pod =head2 default_installer | ||||||||||||||||||||||||||||
| 863 | #pod | ||||||||||||||||||||||||||||
| 864 | #pod This is Sub::Exporter's default installer. It does what Sub::Exporter | ||||||||||||||||||||||||||||
| 865 | #pod promises: it installs code into the target package. | ||||||||||||||||||||||||||||
| 866 | #pod | ||||||||||||||||||||||||||||
| 867 | #pod default_installer(\%arg, \@to_export); | ||||||||||||||||||||||||||||
| 868 | #pod | ||||||||||||||||||||||||||||
| 869 | #pod Passed arguments are: | ||||||||||||||||||||||||||||
| 870 | #pod | ||||||||||||||||||||||||||||
| 871 | #pod into - the package into which exports should be delivered | ||||||||||||||||||||||||||||
| 872 | #pod | ||||||||||||||||||||||||||||
| 873 | #pod C<@to_export> is a list of name/value pairs. The default exporter assigns code | ||||||||||||||||||||||||||||
| 874 | #pod (the values) to named slots (the names) in the given package. If the name is a | ||||||||||||||||||||||||||||
| 875 | #pod scalar reference, the scalar reference is made to point to the code reference | ||||||||||||||||||||||||||||
| 876 | #pod instead. | ||||||||||||||||||||||||||||
| 877 | #pod | ||||||||||||||||||||||||||||
| 878 | #pod =cut | ||||||||||||||||||||||||||||
| 879 | |||||||||||||||||||||||||||||
| 880 | 85 | ▶ | sub default_installer { | ||||||||||||||||||||||||||
|
Subroutine
default_installer: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||||||||||||||||
| 881 | 85 | my ($arg, $to_export) = @_; | |||||||||||||||||||||||||||
| 882 | |||||||||||||||||||||||||||||
| 883 | 85 | ▶ | for (my $i = 0; $i < @$to_export; $i += 2) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 884 | 105 | my ($as, $code) = @$to_export[ $i, $i+1 ]; | |||||||||||||||||||||||||||
| 885 | |||||||||||||||||||||||||||||
| 886 | # Allow as isa ARRAY to push onto an array? | ||||||||||||||||||||||||||||
| 887 | # Allow into isa HASH to install name=>code into hash? | ||||||||||||||||||||||||||||
| 888 | |||||||||||||||||||||||||||||
| 889 | 105 | ▶ | if (ref $as eq 'SCALAR') { | ||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||
| 890 | 2 | $$as = $code; | |||||||||||||||||||||||||||
| 891 | } elsif (ref $as) { | ||||||||||||||||||||||||||||
| 892 | 2 | Carp::croak "invalid reference type for $as: " . ref $as; | |||||||||||||||||||||||||||
| 893 | } else { | ||||||||||||||||||||||||||||
| 894 | Sub::Install::reinstall_sub({ | ||||||||||||||||||||||||||||
| 895 | code => $code, | ||||||||||||||||||||||||||||
| 896 | into => $arg->{into}, | ||||||||||||||||||||||||||||
| 897 | 101 | as => $as | |||||||||||||||||||||||||||
| 898 | }); | ||||||||||||||||||||||||||||
| 899 | } | ||||||||||||||||||||||||||||
| 900 | } | ||||||||||||||||||||||||||||
| 901 | } | ||||||||||||||||||||||||||||
| 902 | |||||||||||||||||||||||||||||
| 903 | 0 | ▶ | sub default_exporter { | ||||||||||||||||||||||||||
|
Subroutine
default_exporter: not called CC=1 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||
| 904 | 0 | Carp::cluck "default_exporter is deprecated; call default_installer instead; the semantics are identical"; | |||||||||||||||||||||||||||
| 905 | 0 | goto &default_installer; | |||||||||||||||||||||||||||
| 906 | } | ||||||||||||||||||||||||||||
| 907 | |||||||||||||||||||||||||||||
| 908 | #pod =head1 EXPORTS | ||||||||||||||||||||||||||||
| 909 | #pod | ||||||||||||||||||||||||||||
| 910 | #pod Sub::Exporter also offers its own exports: the C<setup_exporter> and | ||||||||||||||||||||||||||||
| 911 | #pod C<build_exporter> routines described above. It also provides a special "setup" | ||||||||||||||||||||||||||||
| 912 | #pod collector, which will set up an exporter using the parameters passed to it. | ||||||||||||||||||||||||||||
| 913 | #pod | ||||||||||||||||||||||||||||
| 914 | #pod Note that the "setup" collector (seen in examples like the L</SYNOPSIS> above) | ||||||||||||||||||||||||||||
| 915 | #pod uses C<build_exporter>, not C<setup_exporter>. This means that the special | ||||||||||||||||||||||||||||
| 916 | #pod arguments like "into" and "as" for C<setup_exporter> are not accepted here. | ||||||||||||||||||||||||||||
| 917 | #pod Instead, you may write something like: | ||||||||||||||||||||||||||||
| 918 | #pod | ||||||||||||||||||||||||||||
| 919 | #pod use Sub::Exporter | ||||||||||||||||||||||||||||
| 920 | #pod { into => 'Target::Package' }, | ||||||||||||||||||||||||||||
| 921 | #pod -setup => { | ||||||||||||||||||||||||||||
| 922 | #pod -as => 'do_import', | ||||||||||||||||||||||||||||
| 923 | #pod exports => [ ... ], | ||||||||||||||||||||||||||||
| 924 | #pod } | ||||||||||||||||||||||||||||
| 925 | #pod ; | ||||||||||||||||||||||||||||
| 926 | #pod | ||||||||||||||||||||||||||||
| 927 | #pod Finding a good reason for wanting to do this is left as an exercise for the | ||||||||||||||||||||||||||||
| 928 | #pod reader. | ||||||||||||||||||||||||||||
| 929 | #pod | ||||||||||||||||||||||||||||
| 930 | #pod =cut | ||||||||||||||||||||||||||||
| 931 | |||||||||||||||||||||||||||||
| 932 | setup_exporter({ | ||||||||||||||||||||||||||||
| 933 | exports => [ | ||||||||||||||||||||||||||||
| 934 | qw(setup_exporter build_exporter), | ||||||||||||||||||||||||||||
| 935 | 16 | ▶ | _import => sub { build_exporter($_[2]) }, | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 936 | 16 | ], | |||||||||||||||||||||||||||
| 937 | groups => { | ||||||||||||||||||||||||||||
| 938 | all => [ qw(setup_exporter build_export) ], | ||||||||||||||||||||||||||||
| 939 | }, | ||||||||||||||||||||||||||||
| 940 | collectors => { -setup => \&_setup }, | ||||||||||||||||||||||||||||
| 941 | }); | ||||||||||||||||||||||||||||
| 942 | |||||||||||||||||||||||||||||
| 943 | 18 | ▶ | sub _setup { | ||||||||||||||||||||||||||
|
Subroutine
_setup: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||||||
| 944 | 18 | my ($value, $arg) = @_; | |||||||||||||||||||||||||||
| 945 | |||||||||||||||||||||||||||||
| 946 | 18 | ▶ | if (ref $value eq 'HASH') { | ||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||
| 947 | 14 | push @{ $arg->{import_args} }, [ _import => { -as => 'import', %$value } ]; | |||||||||||||||||||||||||||
| 948 | 14 | return 1; | |||||||||||||||||||||||||||
| 949 | } elsif (ref $value eq 'ARRAY') { | ||||||||||||||||||||||||||||
| 950 | 2 | push @{ $arg->{import_args} }, | |||||||||||||||||||||||||||
| 951 | [ _import => { -as => 'import', exports => $value } ]; | ||||||||||||||||||||||||||||
| 952 | 2 | return 1; | |||||||||||||||||||||||||||
| 953 | } | ||||||||||||||||||||||||||||
| 954 | 2 | return; | |||||||||||||||||||||||||||
| 955 | } | ||||||||||||||||||||||||||||
| 956 | |||||||||||||||||||||||||||||
| 957 | #pod =head1 COMPARISONS | ||||||||||||||||||||||||||||
| 958 | #pod | ||||||||||||||||||||||||||||
| 959 | #pod There are a whole mess of exporters on the CPAN. The features included in | ||||||||||||||||||||||||||||
| 960 | #pod Sub::Exporter set it apart from any existing Exporter. Here's a summary of | ||||||||||||||||||||||||||||
| 961 | #pod some other exporters and how they compare. | ||||||||||||||||||||||||||||
| 962 | #pod | ||||||||||||||||||||||||||||
| 963 | #pod =over | ||||||||||||||||||||||||||||
| 964 | #pod | ||||||||||||||||||||||||||||
| 965 | #pod =item * L<Exporter> and co. | ||||||||||||||||||||||||||||
| 966 | #pod | ||||||||||||||||||||||||||||
| 967 | #pod This is the standard Perl exporter. Its interface is a little clunky, but it's | ||||||||||||||||||||||||||||
| 968 | #pod fast and ubiquitous. It can do some things that Sub::Exporter can't: it can | ||||||||||||||||||||||||||||
| 969 | #pod export things other than routines, it can import "everything in this group | ||||||||||||||||||||||||||||
| 970 | #pod except this symbol," and some other more esoteric things. These features seem | ||||||||||||||||||||||||||||
| 971 | #pod to go nearly entirely unused. | ||||||||||||||||||||||||||||
| 972 | #pod | ||||||||||||||||||||||||||||
| 973 | #pod It always exports things exactly as they appear in the exporting module; it | ||||||||||||||||||||||||||||
| 974 | #pod can't rename or customize routines. Its groups ("tags") can't be nested. | ||||||||||||||||||||||||||||
| 975 | #pod | ||||||||||||||||||||||||||||
| 976 | #pod L<Exporter::Lite> is a whole lot like Exporter, but it does significantly less: | ||||||||||||||||||||||||||||
| 977 | #pod it supports exporting symbols, but not groups, pattern matching, or negation. | ||||||||||||||||||||||||||||
| 978 | #pod | ||||||||||||||||||||||||||||
| 979 | #pod The fact that Sub::Exporter can't export symbols other than subroutines is | ||||||||||||||||||||||||||||
| 980 | #pod a good idea, not a missing feature. | ||||||||||||||||||||||||||||
| 981 | #pod | ||||||||||||||||||||||||||||
| 982 | #pod For simple uses, setting up Sub::Exporter is about as easy as Exporter. For | ||||||||||||||||||||||||||||
| 983 | #pod complex uses, Sub::Exporter makes hard things possible, which would not be | ||||||||||||||||||||||||||||
| 984 | #pod possible with Exporter. | ||||||||||||||||||||||||||||
| 985 | #pod | ||||||||||||||||||||||||||||
| 986 | #pod When using a module that uses Sub::Exporter, users familiar with Exporter will | ||||||||||||||||||||||||||||
| 987 | #pod probably see no difference in the basics. These two lines do about the same | ||||||||||||||||||||||||||||
| 988 | #pod thing in whether the exporting module uses Exporter or Sub::Exporter. | ||||||||||||||||||||||||||||
| 989 | #pod | ||||||||||||||||||||||||||||
| 990 | #pod use Some::Module qw(foo bar baz); | ||||||||||||||||||||||||||||
| 991 | #pod use Some::Module qw(foo :bar baz); | ||||||||||||||||||||||||||||
| 992 | #pod | ||||||||||||||||||||||||||||
| 993 | #pod The definition for exporting in Exporter.pm might look like this: | ||||||||||||||||||||||||||||
| 994 | #pod | ||||||||||||||||||||||||||||
| 995 | #pod package Some::Module; | ||||||||||||||||||||||||||||
| 996 | #pod use base qw(Exporter); | ||||||||||||||||||||||||||||
| 997 | #pod our @EXPORT_OK = qw(foo bar baz quux); | ||||||||||||||||||||||||||||
| 998 | #pod our %EXPORT_TAGS = (bar => [ qw(bar baz) ]); | ||||||||||||||||||||||||||||
| 999 | #pod | ||||||||||||||||||||||||||||
| 1000 | #pod Using Sub::Exporter, it would look like this: | ||||||||||||||||||||||||||||
| 1001 | #pod | ||||||||||||||||||||||||||||
| 1002 | #pod package Some::Module; | ||||||||||||||||||||||||||||
| 1003 | #pod use Sub::Exporter -setup => { | ||||||||||||||||||||||||||||
| 1004 | #pod exports => [ qw(foo bar baz quux) ], | ||||||||||||||||||||||||||||
| 1005 | #pod groups => { bar => [ qw(bar baz) ]} | ||||||||||||||||||||||||||||
| 1006 | #pod }; | ||||||||||||||||||||||||||||
| 1007 | #pod | ||||||||||||||||||||||||||||
| 1008 | #pod Sub::Exporter respects inheritance, so that a package may export inherited | ||||||||||||||||||||||||||||
| 1009 | #pod routines, and will export the most inherited version. Exporting methods | ||||||||||||||||||||||||||||
| 1010 | #pod without currying away the invocant is a bad idea, but Sub::Exporter allows you | ||||||||||||||||||||||||||||
| 1011 | #pod to do just that -- and anyway, there are other uses for this feature, like | ||||||||||||||||||||||||||||
| 1012 | #pod packages of exported subroutines which use inheritance specifically to allow | ||||||||||||||||||||||||||||
| 1013 | #pod more specialized, but similar, packages. | ||||||||||||||||||||||||||||
| 1014 | #pod | ||||||||||||||||||||||||||||
| 1015 | #pod L<Exporter::Easy> provides a wrapper around the standard Exporter. It makes it | ||||||||||||||||||||||||||||
| 1016 | #pod simpler to build groups, but doesn't provide any more functionality. Because | ||||||||||||||||||||||||||||
| 1017 | #pod it is a front-end to Exporter, it will store your exporter's configuration in | ||||||||||||||||||||||||||||
| 1018 | #pod global package variables. | ||||||||||||||||||||||||||||
| 1019 | #pod | ||||||||||||||||||||||||||||
| 1020 | #pod =item * Attribute-Based Exporters | ||||||||||||||||||||||||||||
| 1021 | #pod | ||||||||||||||||||||||||||||
| 1022 | #pod Some exporters use attributes to mark variables to export. L<Exporter::Simple> | ||||||||||||||||||||||||||||
| 1023 | #pod supports exporting any kind of symbol, and supports groups. Using a module | ||||||||||||||||||||||||||||
| 1024 | #pod like Exporter or Sub::Exporter, it's easy to look at one place and see what is | ||||||||||||||||||||||||||||
| 1025 | #pod exported, but it's impossible to look at a variable definition and see whether | ||||||||||||||||||||||||||||
| 1026 | #pod it is exported by that alone. Exporter::Simple makes this trade in reverse: | ||||||||||||||||||||||||||||
| 1027 | #pod each variable's declaration includes its export definition, but there is no one | ||||||||||||||||||||||||||||
| 1028 | #pod place to look to find a manifest of exports. | ||||||||||||||||||||||||||||
| 1029 | #pod | ||||||||||||||||||||||||||||
| 1030 | #pod More importantly, Exporter::Simple does not add any new features to those of | ||||||||||||||||||||||||||||
| 1031 | #pod Exporter. In fact, like Exporter::Easy, it is just a front-end to Exporter, so | ||||||||||||||||||||||||||||
| 1032 | #pod it ends up storing its configuration in global package variables. (This means | ||||||||||||||||||||||||||||
| 1033 | #pod that there is one place to look for your exporter's manifest, actually. You | ||||||||||||||||||||||||||||
| 1034 | #pod can inspect the C<@EXPORT> package variables, and other related package | ||||||||||||||||||||||||||||
| 1035 | #pod variables, at runtime.) | ||||||||||||||||||||||||||||
| 1036 | #pod | ||||||||||||||||||||||||||||
| 1037 | #pod L<Perl6::Export> isn't actually attribute based, but looks similar. Its syntax | ||||||||||||||||||||||||||||
| 1038 | #pod is borrowed from Perl 6, and implemented by a source filter. It is a prototype | ||||||||||||||||||||||||||||
| 1039 | #pod of an interface that is still being designed. It should probably be avoided | ||||||||||||||||||||||||||||
| 1040 | #pod for production work. On the other hand, L<Perl6::Export::Attrs> implements | ||||||||||||||||||||||||||||
| 1041 | #pod Perl 6-like exporting, but translates it into Perl 5 by providing attributes. | ||||||||||||||||||||||||||||
| 1042 | #pod | ||||||||||||||||||||||||||||
| 1043 | #pod =item * Other Exporters | ||||||||||||||||||||||||||||
| 1044 | #pod | ||||||||||||||||||||||||||||
| 1045 | #pod L<Exporter::Renaming> wraps the standard Exporter to allow it to export symbols | ||||||||||||||||||||||||||||
| 1046 | #pod with changed names. | ||||||||||||||||||||||||||||
| 1047 | #pod | ||||||||||||||||||||||||||||
| 1048 | #pod L<Class::Exporter> performs a special kind of routine generation, giving each | ||||||||||||||||||||||||||||
| 1049 | #pod importing package an instance of your class, and then exporting the instance's | ||||||||||||||||||||||||||||
| 1050 | #pod methods as normal routines. (Sub::Exporter, of course, can easily emulate this | ||||||||||||||||||||||||||||
| 1051 | #pod behavior, as shown above.) | ||||||||||||||||||||||||||||
| 1052 | #pod | ||||||||||||||||||||||||||||
| 1053 | #pod L<Exporter::Tidy> implements a form of renaming (using its C<_map> argument) | ||||||||||||||||||||||||||||
| 1054 | #pod and of prefixing, and implements groups. It also avoids using package | ||||||||||||||||||||||||||||
| 1055 | #pod variables for its configuration. | ||||||||||||||||||||||||||||
| 1056 | #pod | ||||||||||||||||||||||||||||
| 1057 | #pod =back | ||||||||||||||||||||||||||||
| 1058 | #pod | ||||||||||||||||||||||||||||
| 1059 | #pod =head1 TODO | ||||||||||||||||||||||||||||
| 1060 | #pod | ||||||||||||||||||||||||||||
| 1061 | #pod =cut | ||||||||||||||||||||||||||||
| 1062 | |||||||||||||||||||||||||||||
| 1063 | #pod =over | ||||||||||||||||||||||||||||
| 1064 | #pod | ||||||||||||||||||||||||||||
| 1065 | #pod =item * write a set of longer, more demonstrative examples | ||||||||||||||||||||||||||||
| 1066 | #pod | ||||||||||||||||||||||||||||
| 1067 | #pod =item * solidify the "custom exporter" interface (see C<&default_exporter>) | ||||||||||||||||||||||||||||
| 1068 | #pod | ||||||||||||||||||||||||||||
| 1069 | #pod =item * add an "always" group | ||||||||||||||||||||||||||||
| 1070 | #pod | ||||||||||||||||||||||||||||
| 1071 | #pod =back | ||||||||||||||||||||||||||||
| 1072 | #pod | ||||||||||||||||||||||||||||
| 1073 | #pod =head1 THANKS | ||||||||||||||||||||||||||||
| 1074 | #pod | ||||||||||||||||||||||||||||
| 1075 | #pod Hans Dieter Pearcey provided helpful advice while I was writing Sub::Exporter. | ||||||||||||||||||||||||||||
| 1076 | #pod Ian Langworth and Shawn Sorichetti asked some good questions and helped me | ||||||||||||||||||||||||||||
| 1077 | #pod improve my documentation quite a bit. Yuval Kogman helped me find a bunch of | ||||||||||||||||||||||||||||
| 1078 | #pod little problems. | ||||||||||||||||||||||||||||
| 1079 | #pod | ||||||||||||||||||||||||||||
| 1080 | #pod Thanks, friends! | ||||||||||||||||||||||||||||
| 1081 | #pod | ||||||||||||||||||||||||||||
| 1082 | #pod =cut | ||||||||||||||||||||||||||||
| 1083 | |||||||||||||||||||||||||||||
| 1084 | 16 | "jn8:32"; # <-- magic true value | |||||||||||||||||||||||||||
| 1085 | |||||||||||||||||||||||||||||
| 1086 | __END__ | ||||||||||||||||||||||||||||