1Importer(3)           User Contributed Perl Documentation          Importer(3)
2
3
4

NAME

6       Importer - Alternative but compatible interface to modules that export
7       symbols.
8

DESCRIPTION

10       This module acts as a layer between Exporter and modules which consume
11       exports. It is feature-compatible with Exporter, plus some much needed
12       extras. You can use this to import symbols from any exporter that
13       follows Exporters specification. The exporter modules themselves do not
14       need to use or inherit from the Exporter module, they just need to set
15       @EXPORT and/or other variables.
16

SYNOPSIS

18           # Import defaults
19           use Importer 'Some::Module';
20
21           # Import a list
22           use Importer 'Another::Module' => qw/foo bar baz/;
23
24           # Import a specific version:
25           use Importer 'That::Module' => '1.00';
26
27           # Require a sepcific version of Importer
28           use Importer 0.001, 'Foo::Bar' => qw/a b c/;
29
30           foo()
31           bar()
32           baz()
33
34           # Remove all subroutines imported by Importer
35           no Importer;
36
37           # Import symbols into variables
38           my $croak = Importer->get_one(Carp => qw/croak/);
39           $croak->("This will croak");
40
41           my $CARP = Importer->get(Carp => qw/croak confess cluck/);
42           $CARP->{croak}->("This will croak");
43           $CARP->{cluck}->("This will cluck");
44           $CARP->{confess}->("This will confess");
45

WHY?

47       There was recently a discussion on p5p about adding features to
48       Exporter.  This conversation raised some significant concerns, those
49       are listed here, in addition to others.
50
51       The burden is on export consumers to specify a version of Exporter
52           Adding a feature to Exporter means that any consumer module that
53           relies on the new features must depend on a specific version of
54           Exporter. This seems somewhat backwards since Exporter is used by
55           the module you are importing from.
56
57       Exporter.pm is really old/crazy code
58           Not much more to say here. It is very old, it is very crazy, and if
59           you break it you break EVERYTHING.
60
61       Using a modules import() for exporting makes it hard to give it other
62       purposes
63           It is not unusual for a module to want to export symbols and
64           provide import behaviors. It is also not unusual for a consumer to
65           only want 1 or the other.  Using this module you can import symbols
66           without also getting the "import()" side effects.
67
68           In addition, moving forward, modules can specify exports and have a
69           custom "import()" without conflating the two. A module can tell you
70           to use Importer to get the symbols, and to use the module directly
71           for behaviors. A module could also use Importer within its own
72           "import()" method without the need to subclass Exporter, or bring
73           in its "import()" method.
74
75       There are other exporter modules on cpan
76           This module normally assumes an exporter uses Exporter, so it looks
77           for the variables and methods Exporter expects. However, other
78           exporters on cpan can override this using the "IMPORTER_MENU()"
79           hook.
80

COMPATIBILITY

82       This module aims for 100% compatibility with every feature of Exporter,
83       plus added features such as import renaming.
84
85       If you find something that works differently, or not at all when
86       compared to Exporter please report it as a bug, unless it is noted as
87       an intentional feature (like import renaming).
88

IMPORT PARAMETERS

90           use Importer $IMPORTER_VERSION, $FROM_MODULE, $FROM_MODULE_VERSION, \&SET_SYMBOL, @SYMBOLS;
91
92       $IMPORTER_VERSION (optional)
93           If you provide a numeric argument as the first argument it will be
94           treated as a version number. Importer will do a version check to
95           make sure it is at least at the requested version.
96
97       $FROM_MODULE (required)
98           This is the only required argument. This is the name of the module
99           to import symbols from.
100
101       $FROM_MODULE_VERSION (optional)
102           Any numeric argument following the $FROM_MODULE will be treated as
103           a version check against $FROM_MODULE.
104
105       \&SET_SYMBOL (optional)
106           Normally Importer will put the exports into your namespace. This is
107           usually done via a more complex form of "*name = $ref". If you do
108           NOT want this to happen then you can provide a custom sub to handle
109           the assignment.
110
111           This is an example that uses this feature to put all the exports
112           into a lexical hash instead of modifying the namespace (This is how
113           the "get()" method is implemented).
114
115               my %CARP;
116               use Importer Carp => sub {
117                   my ($name, $ref) = @_;
118                   $CARP{$name} = $ref;
119               };
120
121               $CARP{cluck}->("This will cluck");
122               $CARP{croak}->("This will croak");
123
124           The first two arguments to the custom sub are the name (no sigil),
125           and the reference. The additional arguments are key/value pairs:
126
127               sub set_symbol {
128                   my ($name, $ref, %info) = @_;
129               }
130
131           $info{from}
132               Package the symbol comes from.
133
134           $info{into}
135               Package to which the symbol should be added.
136
137           $info{sig}
138               The sigil that should be used.
139
140           $info{spec}
141               Extra details.
142
143           $info{symbol}
144               The original symbol name (with sigil) from the original
145               package.
146
147       @SYMBOLS (optional)
148           Symbols you wish to import. If no symbols are specified then the
149           defaults will be used. You may also specify tags using the ':'
150           prefix.
151

SUPPORTED FEATURES

153   TAGS
154       You can define/import subsets of symbols using predefined tags.
155
156           use Importer 'Some::Thing' => ':tag';
157
158       Importer will automatically populate the ":DEFAULT" tag for you.
159       Importer will also give you an ":ALL" tag with ALL exports so long as
160       the exporter does not define a ":ALL" tag already.
161
162   /PATTERN/ or qr/PATTERN/
163       You can import all symbols that match a pattern. The pattern can be
164       supplied a string starting and ending with '/', or you can provide a
165       "qr/../" reference.
166
167           use Importer 'Some::Thing' => '/oo/';
168
169           use Importer 'Some::Thing' => qr/oo/;
170
171   EXCLUDING SYMBOLS
172       You can exclude symbols by prefixing them with '!'.
173
174           use Importer 'Some::Thing'
175               '!foo',         # Exclude one specific symbol
176               '!/pattern/',   # Exclude all matching symbols
177               '!' => qr/oo/,  # Exclude all that match the following arg
178               '!:tag';        # Exclude all in tag
179
180   RENAMING SYMBOLS AT IMPORT
181       This is a new feature, Exporter does not support this on its own.
182
183       You can rename symbols at import time using a specification hash
184       following the import name:
185
186           use Importer 'Some::Thing' => (
187               foo => { -as => 'my_foo' },
188           );
189
190       You can also add a prefix and/or postfix:
191
192           use Importer 'Some::Thing' => (
193               foo => { -prefix => 'my_' },
194           );
195
196       Using this syntax to set prefix and/or postfix also works on tags and
197       patterns that are specified for import, in which case the
198       prefix/postfix is applied to all symbols from the tag/patterm.
199
200   CUSTOM EXPORT ASSIGNMENT
201       This lets you provide an alternative to the "*name = $ref" export
202       assignment.  See the list of parameters to "import()"
203
204   UNIMPORTING
205       See "UNIMPORT PARAMETERS".
206
207   ANONYMOUS EXPORTS
208       See "%EXPORT_ANON".
209
210   GENERATED EXPORTS
211       See "%EXPORT_GEN".
212

UNIMPORT PARAMETERS

214           no Importer;    # Remove all subs brought in with Importer
215
216           no Importer qw/foo bar/;    # Remove only the specified subs
217
218       Only subs can be unimported.
219
220       You can only unimport subs imported using Importer.
221

SUPPORTED VARIABLES

223   @EXPORT
224       This is used exactly the way Exporter uses it.
225
226       List of symbols to export. Sigil is optional for subs. Symbols listed
227       here are exported by default. If possible you should put symbols in
228       @EXPORT_OK instead.
229
230           our @EXPORT = qw/foo bar &baz $BAT/;
231
232   @EXPORT_OK
233       This is used exactly the way Exporter uses it.
234
235       List of symbols that can be imported. Sigil is optional for subs.
236       Symbols listed here are not exported by default. This is preferred over
237       @EXPORT.
238
239           our @EXPORT_OK = qw/foo bar &baz $BAT/;
240
241   %EXPORT_TAGS
242       This module supports tags exactly the way Exporter does.
243
244           use Importer 'Some::Thing'  => ':DEFAULT';
245
246           use Importer 'Other::Thing' => ':some_tag';
247
248       Tags can be specified this way:
249
250           our %EXPORT_TAGS = (
251               oos => [qw/foo boo zoo/],
252               ees => [qw/fee bee zee/],
253           );
254
255   @EXPORT_FAIL
256       This is used exactly the way Exporter uses it.
257
258       Use this to list subs that are not available on all platforms. If
259       someone tries to import one of these, Importer will hit your
260       "$from->export_fail(@items)" callback to try to resolve the issue. See
261       Exporter for documentation of this feature.
262
263           our @EXPORT_FAIL = qw/maybe_bad/;
264
265   %EXPORT_ANON
266       This is new to this module, Exporter does not support it.
267
268       This allows you to export symbols that are not actually in your package
269       symbol table. The keys should be the symbol names, the values are the
270       references for the symbols.
271
272           our %EXPORT_ANON = (
273               '&foo' => sub { 'foo' }
274               '$foo' => \$foo,
275               ...
276           );
277
278   %EXPORT_GEN
279       This is new to this module, Exporter does not support it.
280
281       This allows you to export symbols that are generated on export. The key
282       should be the name of a symbol. The value should be a coderef that
283       produces a reference that will be exported.
284
285       When the generators are called they will receive 2 arguments, the
286       package the symbol is being exported into, and the symbol being
287       imported (name may or may not include sigil for subs).
288
289           our %EXPORT_GEN = (
290               '&foo' => sub {
291                   my $from_package = shift;
292                   my ($into_package, $symbol_name) = @_;
293                   ...
294                   return sub { ... };
295               },
296               ...
297           );
298
299   %EXPORT_MAGIC
300       This is new to this module. Exporter does not support it.
301
302       This allows you to define custom actions to run AFTER an export has
303       been injected into the consumers namespace. This is a good place to
304       enable parser hooks like with Devel::Declare. These will NOT be run if
305       a consumer uses a custom assignment callback.
306
307           our %EXPORT_MAGIC = (
308               foo => sub {
309                   my $from = shift;    # Should be the package doing the exporting
310                   my %args = @_;
311
312                   my $into      = $args{into};         # Package symbol was exported into
313                   my $orig_name = $args{orig_name};    # Original name of the export (in the exporter)
314                   my $new_name  = $args{new_name};     # Name the symbol was imported as
315                   my $ref       = $args{ref};          # The reference to the symbol
316
317                   ...; # whatever you want, return is ignored.
318               },
319           );
320

CLASS METHODS

322       Importer->import($from)
323       Importer->import($from, $version)
324       Importer->import($from, @imports)
325       Importer->import($from, $from_version, @imports)
326       Importer->import($importer_version, $from, ...)
327           This is the magic behind "use Importer ...".
328
329       Importer->import_into($from, $into, @imports)
330       Importer->import_into($from, $level, @imports)
331           You can use this to import symbols from $from into $into. $into may
332           either be a package name, or a caller level to get the name from.
333
334       Importer->unimport()
335       Importer->unimport(@sub_name)
336           This is the magic behind "no Importer ...".
337
338       Importer->unimport_from($from, @sub_names)
339       Importer->unimport_from($level, @sub_names)
340           This lets you remove imported symbols from $from. $from my be a
341           package name, or a caller level.
342
343       my $exports = Importer->get($from, @imports)
344           This returns hashref of "{ $name => $ref }" for all the specified
345           imports.
346
347           $from should be the package from which to get the exports.
348
349       my @export_refs = Importer->get_list($from, @imports)
350           This returns a list of references for each import specified. Only
351           the export references are returned, the names are not.
352
353           $from should be the package from which to get the exports.
354
355       $export_ref = Importer->get_one($from, $import)
356           This returns a single reference to a single export. If you provide
357           multiple imports then only the LAST one will be used.
358
359           $from should be the package from which to get the exports.
360

USING WITH OTHER EXPORTER IMPLEMENTATIONS

362       If you want your module to work with Importer, but you use something
363       other than Exporter to define your exports, you can make it work be
364       defining the "IMPORTER_MENU" method in your package. As well other
365       exporters can be updated to support Importer by putting this sub in
366       your package.  IMPORTER_MENU() must be defined in your package, not a
367       base class!
368
369           sub IMPORTER_MENU {
370               my $class = shift;
371               my ($into, $caller) = @_;
372
373               return (
374                   export       => \@EXPORT,          # Default exports
375                   export_ok    => \@EXPORT_OK,       # Other allowed exports
376                   export_tags  => \%EXPORT_TAGS,     # Define tags
377                   export_fail  => \@EXPORT_FAIL,     # For subs that may not always be available
378                   export_anon  => \%EXPORT_ANON,     # Anonymous symbols to export
379                   export_magic => \%EXPORT_MAGIC,    # Magic to apply after a symbol is exported
380
381                   generate   => \&GENERATE,          # Sub to generate dynamic exports
382                                                      # OR
383                   export_gen => \%EXPORT_GEN,        # Hash of builders, key is symbol
384                                                      # name, value is sub that generates
385                                                      # the symbol ref.
386               );
387           }
388
389           sub GENERATE {
390               my ($symbol) = @_;
391
392               ...
393
394               return $ref;
395           }
396
397       All exports must be listed in either @EXPORT or @EXPORT_OK, or be keys
398       in %EXPORT_GEN or %EXPORT_ANON to be allowed. 'export_tags',
399       'export_fail', 'export_anon', 'export_gen', and 'generate' are
400       optional. You cannot combine 'generate' and 'export_gen'.
401
402       Note: If your GENERATE sub needs the $class, $into, or $caller then
403       your "IMPORTER_MENU()" method will need to build an anonymous sub that
404       closes over them:
405
406           sub IMPORTER_MENU {
407               my $class = shift;
408               my ($into, $caller) = @_;
409
410               return (
411                   ...
412                   generate => sub { $class->GENERATE($into, $caller, @_) },
413               );
414           }
415

OO Interface

417           use Importer;
418
419           my $imp = Importer->new(from => 'Some::Exporter');
420
421           $imp->do_import('Destination::Package');
422           $imp->do_import('Another::Destination', @symbols);
423
424       Or, maybe more useful:
425
426           my $imp = Importer->new(from => 'Carp');
427           my $croak = $imp->get_one('croak');
428           $croak->("This will croak");
429
430   OBJECT CONSTRUCTION
431       $imp = Importer->new(from => 'Some::Exporter')
432       $imp = Importer->new(from => 'Some::Exporter', caller => [$package,
433       $file, $line])
434           This is how you create a new Importer instance. "from =>
435           'Some::Exporter'" is the only required argument. You may also
436           specify the "caller => [...]"  arrayref, which will be used only
437           for error reporting. If you do not specify a caller then Importer
438           will attempt to find the caller dynamically every time it needs it
439           (this is slow and expensive, but necessary if you intend to re-use
440           the object.)
441
442   OBJECT METHODS
443       $imp->do_import($into)
444       $imp->do_import($into, @symbols)
445           This will import from the objects "from" package into the $into
446           package.  You can provide a list of @symbols, or you can leave it
447           empty for the defaults.
448
449       $imp->do_unimport()
450       $imp->do_unimport(@symbols)
451           This will remove imported symbols from the objects "from" package.
452           If you specify a list of @symbols then only the specified symbols
453           will be removed, otherwise all symbols imported using Importer will
454           be removed.
455
456           Note: Please be aware of the difference between "do_import()" and
457           "do_unimport()". For import 'from' us used as the origin, in
458           unimport it is used as the target. This means you cannot re-use an
459           instance to import and then unimport.
460
461       ($into, $versions, $exclude, $symbols, $set) =
462       $imp->parse_args('Dest::Package')
463       ($into, $versions, $exclude, $symbols, $set) =
464       $imp->parse_args('Dest::Package', @symbols)
465           This parses arguments. The first argument must be the destination
466           package.  Other arguments can be a mix of symbol names, tags,
467           patterns, version numbers, and exclusions.
468
469       $caller_ref = $imp->get_caller()
470           This will find the caller. This is mainly used for error reporting.
471           IF the object was constructed with a caller then that is what is
472           returned, otherwise this will scan the stack looking for the first
473           call that does not originate from a package that ISA Importer.
474
475       $imp->carp($warning)
476           Warn at the callers level.
477
478       $imp->croak($exception)
479           Die at the callers level.
480
481       $from_package = $imp->from()
482           Get the "from" package that was specified at construction.
483
484       $file = $imp->from_file()
485           Get the filename for the "from" package.
486
487       $imp->load_from()
488           This will load the "from" package if it has not been loaded
489           already. This uses some magic to ensure errors in the load process
490           are reported to the "caller".
491
492       $menu_hr = $imp->menu($into)
493           Get the export menu built from, or provided by the "from" package.
494           This is cached after the first time it is called. Use
495           "$imp->reload_menu()" to refresh it.
496
497           The menu structure looks like this:
498
499               $menu = {
500                   # every valid export has a key in the lookup hashref, value is always
501                   # 1, key always includes the sigil
502                   lookup => {'&symbol_a' => 1, '$symbol_b' => 1, ...},
503
504                   # most exports are listed here, symbol name with sigil is key, value is
505                   # a reference to the symbol. If a symbol is missing it may be generated.
506                   exports => {'&symbol_a' => \&symbol_a, '$symbol_b' => \$symbol_b, ...},
507
508                   # Hashref of tags, tag name (without ':' prefix) is key, value is an
509                   # arrayref of symbol names, subs may have a sigil, but are not required
510                   # to.
511                   tags => { DEFAULT => [...], foo => [...], ... },
512
513                   # Magic to apply
514                   magic => { foo => sub { ... }, ... },
515
516                   # This is a hashref just like 'lookup'. Keys are symbols which may not
517                   # always be available. If there are no symbols in this category then
518                   # the value of the 'fail' key will be undef instead of a hashref.
519                   fail => { '&iffy_symbol' => 1, '\&only_on_linux' => 1 },
520                   # OR fail => undef,
521
522                   # If present, this subroutine knows how to generate references for the
523                   # symbols listed in 'lookup', but missing from 'exports'. References
524                   # this returns are NEVER cached.
525                   generate => sub { my $sym_name = shift; ...; return $symbol_ref },
526               };
527
528       $imp->reload_menu($into)
529           This will reload the export menu from the "from" package.
530
531       my $exports = $imp->get(@imports)
532           This returns hashref of "{ $name => $ref }" for all the specified
533           imports.
534
535       my @export_refs = $imp->get_list(@imports)
536           This returns a list of references for each import specified. Only
537           the export references are returned, the names are not.
538
539       $export_ref = $imp->get_one($import)
540           This returns a single reference to a single export. If you provide
541           multiple imports then only the LAST one will be used.
542

FUNCTIONS

544       These can be imported:
545
546           use Importer 'Importer' => qw/import optimal_import/;
547
548       $bool = optimal_import($from, $into, \@caller, @imports)
549           This function will attempt to import @imports from the $from
550           package into the $into package. @caller needs to have a package
551           name, filename, and line number. If this function fails then no
552           exporting will actually happen.
553
554           If the import is successful this will return true.
555
556           If the import is unsuccessful this will return false, and no
557           modifications to the symbol table will occur.
558
559       $class->import(@imports)
560           If you write class intended to be used with Importer, but also need
561           to provide a legacy "import()" method for direct consumers of your
562           class, you can import this "import()" method.
563
564               package My::Exporter;
565
566               # This will give you 'import()' much like 'use base "Exporter";'
567               use Importer 'Importer' => qw/import/;
568
569               ...
570

SOURCE

572       The source code repository for Importer can be found at
573       <http://github.com/exodist/Importer>.
574

MAINTAINERS

576       Chad Granum <exodist@cpan.org>
577

AUTHORS

579       Chad Granum <exodist@cpan.org>
580
582       Copyright 2015 Chad Granum <exodist7@gmail.com>.
583
584       This program is free software; you can redistribute it and/or modify it
585       under the same terms as Perl itself.
586
587       See <http://dev.perl.org/licenses/>
588
589
590
591perl v5.30.1                      2020-01-30                       Importer(3)
Impressum