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
73 in 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()"
79 hook.
80
82 This module aims for 100% compatibility with every feature of Exporter,
83 plus added features such as import renaming.
84 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
90 use Importer $IMPORTER_VERSION, $FROM_MODULE, $FROM_MODULE_VERSION, \&SET_SYMBOL, @SYMBOLS;
91 $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 $FROM_MODULE (required)
98 This is the only required argument. This is the name of the module
99 to import symbols from.
100 $FROM_MODULE_VERSION (optional)
102 Any numeric argument following the $FROM_MODULE will be treated as
103 a version check against $FROM_MODULE.
104 \&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 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 my %CARP;
116 use Importer Carp => sub {
117 my ($name, $ref) = @_;
118 $CARP{$name} = $ref;
119 };
120 $CARP{cluck}->("This will cluck");
122 $CARP{croak}->("This will croak");
123 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 sub set_symbol {
128 my ($name, $ref, %info) = @_;
129 }
130 $info{from}
132 Package the symbol comes from.
133 $info{into}
135 Package to which the symbol should be added.
136 $info{sig}
138 The sigil that should be used.
139 $info{spec}
141 Extra details.
142 $info{symbol}
144 The original symbol name (with sigil) from the original
145 package.
146 @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
153 TAGS
154 You can define/import subsets of symbols using predefined tags.
155 use Importer 'Some::Thing' => ':tag';
157 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 /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 use Importer 'Some::Thing' => '/oo/';
168 use Importer 'Some::Thing' => qr/oo/;
170 EXCLUDING SYMBOLS
172 You can exclude symbols by prefixing them with '!'.
173 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 RENAMING SYMBOLS AT IMPORT
181 This is a new feature, Exporter does not support this on its own.
182 You can rename symbols at import time using a specification hash
184 following the import name:
185 use Importer 'Some::Thing' => (
187 foo => { -as => 'my_foo' },
188 );
189 You can also add a prefix and/or postfix:
191 use Importer 'Some::Thing' => (
193 foo => { -prefix => 'my_' },
194 );
195 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 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 UNIMPORTING
205 See "UNIMPORT PARAMETERS".
206 ANONYMOUS EXPORTS
208 See "%EXPORT_ANON".
209 GENERATED EXPORTS
211 See "%EXPORT_GEN".
212
214 no Importer; # Remove all subs brought in with Importer
215 no Importer qw/foo bar/; # Remove only the specified subs
217 Only subs can be unimported.
219 You can only unimport subs imported using Importer.
221
223 @EXPORT
224 This is used exactly the way Exporter uses it.
225 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 our @EXPORT = qw/foo bar &baz $BAT/;
231 @EXPORT_OK
233 This is used exactly the way Exporter uses it.
234 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 our @EXPORT_OK = qw/foo bar &baz $BAT/;
240 %EXPORT_TAGS
242 This module supports tags exactly the way Exporter does.
243 use Importer 'Some::Thing' => ':DEFAULT';
245 use Importer 'Other::Thing' => ':some_tag';
247 Tags can be specified this way:
249 our %EXPORT_TAGS = (
251 oos => [qw/foo boo zoo/],
252 ees => [qw/fee bee zee/],
253 );
254 @EXPORT_FAIL
256 This is used exactly the way Exporter uses it.
257 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 our @EXPORT_FAIL = qw/maybe_bad/;
264 %EXPORT_ANON
266 This is new to this module, Exporter does not support it.
267 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 our %EXPORT_ANON = (
273 '&foo' => sub { 'foo' }
274 '$foo' => \$foo,
275 ...
276 );
277 %EXPORT_GEN
279 This is new to this module, Exporter does not support it.
280 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 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 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 %EXPORT_MAGIC
300 This is new to this module. Exporter does not support it.
301 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 our %EXPORT_MAGIC = (
308 foo => sub {
309 my $from = shift; # Should be the package doing the exporting
310 my %args = @_;
311 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 ...; # whatever you want, return is ignored.
318 },
319 );
320
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 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 Importer->unimport()
335 Importer->unimport(@sub_name)
336 This is the magic behind "no Importer ...".
337 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 my $exports = Importer->get($from, @imports)
344 This returns hashref of "{ $name => $ref }" for all the specified
345 imports.
346 $from should be the package from which to get the exports.
348 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 $from should be the package from which to get the exports.
354 $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 $from should be the package from which to get the exports.
360
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 sub IMPORTER_MENU {
370 my $class = shift;
371 my ($into, $caller) = @_;
372 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 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 sub GENERATE {
390 my ($symbol) = @_;
391 ...
393 return $ref;
395 }
396 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 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 sub IMPORTER_MENU {
407 my $class = shift;
408 my ($into, $caller) = @_;
409 return (
411 ...
412 generate => sub { $class->GENERATE($into, $caller, @_) },
413 );
414 }
415
417 use Importer;
418 my $imp = Importer->new(from => 'Some::Exporter');
420 $imp->do_import('Destination::Package');
422 $imp->do_import('Another::Destination', @symbols);
423 Or, maybe more useful:
425 my $imp = Importer->new(from => 'Carp');
427 my $croak = $imp->get_one('croak');
428 $croak->("This will croak");
429 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 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 $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 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 ($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 $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 $imp->carp($warning)
476 Warn at the callers level.
477 $imp->croak($exception)
479 Die at the callers level.
480 $from_package = $imp->from()
482 Get the "from" package that was specified at construction.
483 $file = $imp->from_file()
485 Get the filename for the "from" package.
486 $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 $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 The menu structure looks like this:
498 $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 # 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 # 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 # Magic to apply
514 magic => { foo => sub { ... }, ... },
515 # 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 # 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 $imp->reload_menu($into)
529 This will reload the export menu from the "from" package.
530 my $exports = $imp->get(@imports)
532 This returns hashref of "{ $name => $ref }" for all the specified
533 imports.
534 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 $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
544 These can be imported:
545 use Importer 'Importer' => qw/import optimal_import/;
547 $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 If the import is successful this will return true.
555 If the import is unsuccessful this will return false, and no
557 modifications to the symbol table will occur.
558 $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 package My::Exporter;
565 # This will give you 'import()' much like 'use base "Exporter";'
567 use Importer 'Importer' => qw/import/;
568 ...
570
572 The source code repository for Importer can be found at
573 <http://github.com/exodist/Importer>.
574
576 Chad Granum <exodist@cpan.org>
577
579 Chad Granum <exodist@cpan.org>
580
582 Copyright 2015 Chad Granum <exodist7@gmail.com>.
583 This program is free software; you can redistribute it and/or modify it
585 under the same terms as Perl itself.
586 See <http://dev.perl.org/licenses/>
588perl v5.36.0 2022-07-22 Importer(3)