1Importer(3) User Contributed Perl Documentation Importer(3)
2
6 Importer - Alternative but compatible interface to modules that export
7 symbols.
8
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
18 # Import defaults
19 use Importer 'Some::Module';
20 # Import a list
22 use Importer 'Another::Module' => qw/foo bar baz/;
23 # Import a specific version:
25 use Importer 'That::Module' => '1.00';
26 # Require a sepcific version of Importer
28 use Importer 0.001, 'Foo::Bar' => qw/a b c/;
29 foo()
31 bar()
32 baz()
33 # Remove all subroutines imported by Importer
35 no Importer;
36 # Import symbols into variables
38 my $croak = Importer->get_one(Carp => qw/croak/);
39 $croak->("This will croak");
40 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
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 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 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 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 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 in
73 its import() method.
74 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() hook.
79
81 This module aims for 100% compatibility with every feature of Exporter,
82 plus added features such as import renaming.
83 If you find something that works differently, or not at all when
85 compared to Exporter please report it as a bug, unless it is noted as
86 an intentional feature (like import renaming).
87
89 use Importer $IMPORTER_VERSION, $FROM_MODULE, $FROM_MODULE_VERSION, \&SET_SYMBOL, @SYMBOLS;
90 $IMPORTER_VERSION (optional)
92 If you provide a numeric argument as the first argument it will be
93 treated as a version number. Importer will do a version check to
94 make sure it is at least at the requested version.
95 $FROM_MODULE (required)
97 This is the only required argument. This is the name of the module
98 to import symbols from.
99 $FROM_MODULE_VERSION (optional)
101 Any numeric argument following the $FROM_MODULE will be treated as
102 a version check against $FROM_MODULE.
103 \&SET_SYMBOL (optional)
105 Normally Importer will put the exports into your namespace. This is
106 usually done via a more complex form of "*name = $ref". If you do
107 NOT want this to happen then you can provide a custom sub to handle
108 the assignment.
109 This is an example that uses this feature to put all the exports
111 into a lexical hash instead of modifying the namespace (This is how
112 the get() method is implemented).
113 my %CARP;
115 use Importer Carp => sub {
116 my ($name, $ref) = @_;
117 $CARP{$name} = $ref;
118 };
119 $CARP{cluck}->("This will cluck");
121 $CARP{croak}->("This will croak");
122 The first two arguments to the custom sub are the name (no sigil),
124 and the reference. The additional arguments are key/value pairs:
125 sub set_symbol {
127 my ($name, $ref, %info) = @_;
128 }
129 $info{from}
131 Package the symbol comes from.
132 $info{into}
134 Package to which the symbol should be added.
135 $info{sig}
137 The sigil that should be used.
138 $info{spec}
140 Extra details.
141 $info{symbol}
143 The original symbol name (with sigil) from the original
144 package.
145 @SYMBOLS (optional)
147 Symbols you wish to import. If no symbols are specified then the
148 defaults will be used. You may also specify tags using the ':'
149 prefix.
150
152 TAGS
153 You can define/import subsets of symbols using predefined tags.
154 use Importer 'Some::Thing' => ':tag';
156 Importer will automatically populate the ":DEFAULT" tag for you.
158 Importer will also give you an ":ALL" tag with ALL exports so long as
159 the exporter does not define a ":ALL" tag already.
160 /PATTERN/ or qr/PATTERN/
162 You can import all symbols that match a pattern. The pattern can be
163 supplied a string starting and ending with '/', or you can provide a
164 "qr/../" reference.
165 use Importer 'Some::Thing' => '/oo/';
167 use Importer 'Some::Thing' => qr/oo/;
169 EXCLUDING SYMBOLS
171 You can exclude symbols by prefixing them with '!'.
172 use Importer 'Some::Thing'
174 '!foo', # Exclude one specific symbol
175 '!/pattern/', # Exclude all matching symbols
176 '!' => qr/oo/, # Exclude all that match the following arg
177 '!:tag'; # Exclude all in tag
178 RENAMING SYMBOLS AT IMPORT
180 This is a new feature, Exporter does not support this on its own.
181 You can rename symbols at import time using a specification hash
183 following the import name:
184 use Importer 'Some::Thing' => (
186 foo => { -as => 'my_foo' },
187 );
188 You can also add a prefix and/or postfix:
190 use Importer 'Some::Thing' => (
192 foo => { -prefix => 'my_' },
193 );
194 Using this syntax to set prefix and/or postfix also works on tags and
196 patterns that are specified for import, in which case the
197 prefix/postfix is applied to all symbols from the tag/patterm.
198 CUSTOM EXPORT ASSIGNMENT
200 This lets you provide an alternative to the "*name = $ref" export
201 assignment. See the list of parameters to import()
202 UNIMPORTING
204 See "UNIMPORT PARAMETERS".
205 ANONYMOUS EXPORTS
207 See "%EXPORT_ANON".
208 GENERATED EXPORTS
210 See "%EXPORT_GEN".
211
213 no Importer; # Remove all subs brought in with Importer
214 no Importer qw/foo bar/; # Remove only the specified subs
216 Only subs can be unimported.
218 You can only unimport subs imported using Importer.
220
222 @EXPORT
223 This is used exactly the way Exporter uses it.
224 List of symbols to export. Sigil is optional for subs. Symbols listed
226 here are exported by default. If possible you should put symbols in
227 @EXPORT_OK instead.
228 our @EXPORT = qw/foo bar &baz $BAT/;
230 @EXPORT_OK
232 This is used exactly the way Exporter uses it.
233 List of symbols that can be imported. Sigil is optional for subs.
235 Symbols listed here are not exported by default. This is preferred over
236 @EXPORT.
237 our @EXPORT_OK = qw/foo bar &baz $BAT/;
239 %EXPORT_TAGS
241 This module supports tags exactly the way Exporter does.
242 use Importer 'Some::Thing' => ':DEFAULT';
244 use Importer 'Other::Thing' => ':some_tag';
246 Tags can be specified this way:
248 our %EXPORT_TAGS = (
250 oos => [qw/foo boo zoo/],
251 ees => [qw/fee bee zee/],
252 );
253 @EXPORT_FAIL
255 This is used exactly the way Exporter uses it.
256 Use this to list subs that are not available on all platforms. If
258 someone tries to import one of these, Importer will hit your
259 "$from->export_fail(@items)" callback to try to resolve the issue. See
260 Exporter for documentation of this feature.
261 our @EXPORT_FAIL = qw/maybe_bad/;
263 %EXPORT_ANON
265 This is new to this module, Exporter does not support it.
266 This allows you to export symbols that are not actually in your package
268 symbol table. The keys should be the symbol names, the values are the
269 references for the symbols.
270 our %EXPORT_ANON = (
272 '&foo' => sub { 'foo' }
273 '$foo' => \$foo,
274 ...
275 );
276 %EXPORT_GEN
278 This is new to this module, Exporter does not support it.
279 This allows you to export symbols that are generated on export. The key
281 should be the name of a symbol. The value should be a coderef that
282 produces a reference that will be exported.
283 When the generators are called they will receive 2 arguments, the
285 package the symbol is being exported into, and the symbol being
286 imported (name may or may not include sigil for subs).
287 our %EXPORT_GEN = (
289 '&foo' => sub {
290 my $from_package = shift;
291 my ($into_package, $symbol_name) = @_;
292 ...
293 return sub { ... };
294 },
295 ...
296 );
297 %EXPORT_MAGIC
299 This is new to this module. Exporter does not support it.
300 This allows you to define custom actions to run AFTER an export has
302 been injected into the consumers namespace. This is a good place to
303 enable parser hooks like with Devel::Declare. These will NOT be run if
304 a consumer uses a custom assignment callback.
305 our %EXPORT_MAGIC = (
307 foo => sub {
308 my $from = shift; # Should be the package doing the exporting
309 my %args = @_;
310 my $into = $args{into}; # Package symbol was exported into
312 my $orig_name = $args{orig_name}; # Original name of the export (in the exporter)
313 my $new_name = $args{new_name}; # Name the symbol was imported as
314 my $ref = $args{ref}; # The reference to the symbol
315 ...; # whatever you want, return is ignored.
317 },
318 );
319
321 Importer->import($from)
322 Importer->import($from, $version)
323 Importer->import($from, @imports)
324 Importer->import($from, $from_version, @imports)
325 Importer->import($importer_version, $from, ...)
326 This is the magic behind "use Importer ...".
327 Importer->import_into($from, $into, @imports)
329 Importer->import_into($from, $level, @imports)
330 You can use this to import symbols from $from into $into. $into may
331 either be a package name, or a caller level to get the name from.
332 Importer->unimport()
334 Importer->unimport(@sub_name)
335 This is the magic behind "no Importer ...".
336 Importer->unimport_from($from, @sub_names)
338 Importer->unimport_from($level, @sub_names)
339 This lets you remove imported symbols from $from. $from my be a
340 package name, or a caller level.
341 my $exports = Importer->get($from, @imports)
343 This returns hashref of "{ $name => $ref }" for all the specified
344 imports.
345 $from should be the package from which to get the exports.
347 my @export_refs = Importer->get_list($from, @imports)
349 This returns a list of references for each import specified. Only
350 the export references are returned, the names are not.
351 $from should be the package from which to get the exports.
353 $export_ref = Importer->get_one($from, $import)
355 This returns a single reference to a single export. If you provide
356 multiple imports then only the LAST one will be used.
357 $from should be the package from which to get the exports.
359
361 If you want your module to work with Importer, but you use something
362 other than Exporter to define your exports, you can make it work be
363 defining the "IMPORTER_MENU" method in your package. As well other
364 exporters can be updated to support Importer by putting this sub in
365 your package. IMPORTER_MENU() must be defined in your package, not a
366 base class!
367 sub IMPORTER_MENU {
369 my $class = shift;
370 my ($into, $caller) = @_;
371 return (
373 export => \@EXPORT, # Default exports
374 export_ok => \@EXPORT_OK, # Other allowed exports
375 export_tags => \%EXPORT_TAGS, # Define tags
376 export_fail => \@EXPORT_FAIL, # For subs that may not always be available
377 export_anon => \%EXPORT_ANON, # Anonymous symbols to export
378 export_magic => \%EXPORT_MAGIC, # Magic to apply after a symbol is exported
379 generate => \&GENERATE, # Sub to generate dynamic exports
381 # OR
382 export_gen => \%EXPORT_GEN, # Hash of builders, key is symbol
383 # name, value is sub that generates
384 # the symbol ref.
385 );
386 }
387 sub GENERATE {
389 my ($symbol) = @_;
390 ...
392 return $ref;
394 }
395 All exports must be listed in either @EXPORT or @EXPORT_OK, or be keys
397 in %EXPORT_GEN or %EXPORT_ANON to be allowed. 'export_tags',
398 'export_fail', 'export_anon', 'export_gen', and 'generate' are
399 optional. You cannot combine 'generate' and 'export_gen'.
400 Note: If your GENERATE sub needs the $class, $into, or $caller then
402 your IMPORTER_MENU() method will need to build an anonymous sub that
403 closes over them:
404 sub IMPORTER_MENU {
406 my $class = shift;
407 my ($into, $caller) = @_;
408 return (
410 ...
411 generate => sub { $class->GENERATE($into, $caller, @_) },
412 );
413 }
414
416 use Importer;
417 my $imp = Importer->new(from => 'Some::Exporter');
419 $imp->do_import('Destination::Package');
421 $imp->do_import('Another::Destination', @symbols);
422 Or, maybe more useful:
424 my $imp = Importer->new(from => 'Carp');
426 my $croak = $imp->get_one('croak');
427 $croak->("This will croak");
428 OBJECT CONSTRUCTION
430 $imp = Importer->new(from => 'Some::Exporter')
431 $imp = Importer->new(from => 'Some::Exporter', caller => [$package,
432 $file, $line])
433 This is how you create a new Importer instance. "from =>
434 'Some::Exporter'" is the only required argument. You may also
435 specify the "caller => [...]" arrayref, which will be used only
436 for error reporting. If you do not specify a caller then Importer
437 will attempt to find the caller dynamically every time it needs it
438 (this is slow and expensive, but necessary if you intend to re-use
439 the object.)
440 OBJECT METHODS
442 $imp->do_import($into)
443 $imp->do_import($into, @symbols)
444 This will import from the objects "from" package into the $into
445 package. You can provide a list of @symbols, or you can leave it
446 empty for the defaults.
447 $imp->do_unimport()
449 $imp->do_unimport(@symbols)
450 This will remove imported symbols from the objects "from" package.
451 If you specify a list of @symbols then only the specified symbols
452 will be removed, otherwise all symbols imported using Importer will
453 be removed.
454 Note: Please be aware of the difference between do_import() and
456 do_unimport(). For import 'from' us used as the origin, in unimport
457 it is used as the target. This means you cannot re-use an instance
458 to import and then unimport.
459 ($into, $versions, $exclude, $symbols, $set) =
461 $imp->parse_args('Dest::Package')
462 ($into, $versions, $exclude, $symbols, $set) =
463 $imp->parse_args('Dest::Package', @symbols)
464 This parses arguments. The first argument must be the destination
465 package. Other arguments can be a mix of symbol names, tags,
466 patterns, version numbers, and exclusions.
467 $caller_ref = $imp->get_caller()
469 This will find the caller. This is mainly used for error reporting.
470 IF the object was constructed with a caller then that is what is
471 returned, otherwise this will scan the stack looking for the first
472 call that does not originate from a package that ISA Importer.
473 $imp->carp($warning)
475 Warn at the callers level.
476 $imp->croak($exception)
478 Die at the callers level.
479 $from_package = $imp->from()
481 Get the "from" package that was specified at construction.
482 $file = $imp->from_file()
484 Get the filename for the "from" package.
485 $imp->load_from()
487 This will load the "from" package if it has not been loaded
488 already. This uses some magic to ensure errors in the load process
489 are reported to the "caller".
490 $menu_hr = $imp->menu($into)
492 Get the export menu built from, or provided by the "from" package.
493 This is cached after the first time it is called. Use
494 "$imp->reload_menu()" to refresh it.
495 The menu structure looks like this:
497 $menu = {
499 # every valid export has a key in the lookup hashref, value is always
500 # 1, key always includes the sigil
501 lookup => {'&symbol_a' => 1, '$symbol_b' => 1, ...},
502 # most exports are listed here, symbol name with sigil is key, value is
504 # a reference to the symbol. If a symbol is missing it may be generated.
505 exports => {'&symbol_a' => \&symbol_a, '$symbol_b' => \$symbol_b, ...},
506 # Hashref of tags, tag name (without ':' prefix) is key, value is an
508 # arrayref of symbol names, subs may have a sigil, but are not required
509 # to.
510 tags => { DEFAULT => [...], foo => [...], ... },
511 # Magic to apply
513 magic => { foo => sub { ... }, ... },
514 # This is a hashref just like 'lookup'. Keys are symbols which may not
516 # always be available. If there are no symbols in this category then
517 # the value of the 'fail' key will be undef instead of a hashref.
518 fail => { '&iffy_symbol' => 1, '\&only_on_linux' => 1 },
519 # OR fail => undef,
520 # If present, this subroutine knows how to generate references for the
522 # symbols listed in 'lookup', but missing from 'exports'. References
523 # this returns are NEVER cached.
524 generate => sub { my $sym_name = shift; ...; return $symbol_ref },
525 };
526 $imp->reload_menu($into)
528 This will reload the export menu from the "from" package.
529 my $exports = $imp->get(@imports)
531 This returns hashref of "{ $name => $ref }" for all the specified
532 imports.
533 my @export_refs = $imp->get_list(@imports)
535 This returns a list of references for each import specified. Only
536 the export references are returned, the names are not.
537 $export_ref = $imp->get_one($import)
539 This returns a single reference to a single export. If you provide
540 multiple imports then only the LAST one will be used.
541
543 These can be imported:
544 use Importer 'Importer' => qw/import optimal_import/;
546 $bool = optimal_import($from, $into, \@caller, @imports)
548 This function will attempt to import @imports from the $from
549 package into the $into package. @caller needs to have a package
550 name, filename, and line number. If this function fails then no
551 exporting will actually happen.
552 If the import is successful this will return true.
554 If the import is unsuccessful this will return false, and no
556 modifications to the symbol table will occur.
557 $class->import(@imports)
559 If you write class intended to be used with Importer, but also need
560 to provide a legacy import() method for direct consumers of your
561 class, you can import this import() method.
562 package My::Exporter;
564 # This will give you 'import()' much like 'use base "Exporter";'
566 use Importer 'Importer' => qw/import/;
567 ...
569
571 The source code repository for Importer can be found at
572 <http://github.com/exodist/Importer>.
573
575 Chad Granum <exodist@cpan.org>
576
578 Chad Granum <exodist@cpan.org>
579
581 Copyright 2015 Chad Granum <exodist7@gmail.com>.
582 This program is free software; you can redistribute it and/or modify it
584 under the same terms as Perl itself.
585 See <http://dev.perl.org/licenses/>
587perl v5.36.0 2023-01-20 Importer(3)