Exporter(3pm)

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

NAME

6       Exporter - Implements default import method for modules
7

SYNOPSIS

9       In module YourModule.pm:
10
11         package YourModule;
12         use Exporter 'import';
13         our @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
14
15       or
16
17         package YourModule;
18         require Exporter;
19         our @ISA = qw(Exporter);  # inherit all of Exporter's methods
20         our @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
21
22       or
23
24         package YourModule;
25         use parent 'Exporter';  # inherit all of Exporter's methods
26         our @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
27
28       In other files which wish to use "YourModule":
29
30         use YourModule qw(frobnicate);      # import listed symbols
31         frobnicate ($left, $right)          # calls YourModule::frobnicate
32
33       Take a look at "Good Practices" for some variants you will like to use
34       in modern Perl code.
35

DESCRIPTION

37       The Exporter module implements an "import" method which allows a module
38       to export functions and variables to its users' namespaces.  Many
39       modules use Exporter rather than implementing their own "import" method
40       because Exporter provides a highly flexible interface, with an
41       implementation optimised for the common case.
42
43       Perl automatically calls the "import" method when processing a "use"
44       statement for a module.  Modules and "use" are documented in perlfunc
45       and perlmod.  Understanding the concept of modules and how the "use"
46       statement operates is important to understanding the Exporter.
47
48   How to Export
49       The arrays @EXPORT and @EXPORT_OK in a module hold lists of symbols
50       that are going to be exported into the users name space by default, or
51       which they can request to be exported, respectively.  The symbols can
52       represent functions, scalars, arrays, hashes, or typeglobs.  The
53       symbols must be given by full name with the exception that the
54       ampersand in front of a function is optional, e.g.
55
56         our @EXPORT    = qw(afunc $scalar @array);   # afunc is a function
57         our @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
58
59       If you are only exporting function names it is recommended to omit the
60       ampersand, as the implementation is faster this way.
61
62   Selecting What to Export
63       Do not export method names!
64
65       Do not export anything else by default without a good reason!
66
67       Exports pollute the namespace of the module user.  If you must export
68       try to use @EXPORT_OK in preference to @EXPORT and avoid short or
69       common symbol names to reduce the risk of name clashes.
70
71       Generally anything not exported is still accessible from outside the
72       module using the "YourModule::item_name" (or "$blessed_ref->method")
73       syntax.  By convention you can use a leading underscore on names to
74       informally indicate that they are 'internal' and not for public use.
75
76       (It is actually possible to get private functions by saying:
77
78         my $subref = sub { ... };
79         $subref->(@args);            # Call it as a function
80         $obj->$subref(@args);        # Use it as a method
81
82       However if you use them for methods it is up to you to figure out how
83       to make inheritance work.)
84
85       As a general rule, if the module is trying to be object oriented then
86       export nothing.  If it's just a collection of functions then @EXPORT_OK
87       anything but use @EXPORT with caution.  For function and method names
88       use barewords in preference to names prefixed with ampersands for the
89       export lists.
90
91       Other module design guidelines can be found in perlmod.
92
93   How to Import
94       In other files which wish to use your module there are three basic ways
95       for them to load your module and import its symbols:
96
97       "use YourModule;"
98           This imports all the symbols from YourModule's @EXPORT into the
99           namespace of the "use" statement.
100
101       "use YourModule ();"
102           This causes perl to load your module but does not import any
103           symbols.
104
105       "use YourModule qw(...);"
106           This imports only the symbols listed by the caller into their
107           namespace.  All listed symbols must be in your @EXPORT or
108           @EXPORT_OK, else an error occurs.  The advanced export features of
109           Exporter are accessed like this, but with list entries that are
110           syntactically distinct from symbol names.
111
112       Unless you want to use its advanced features, this is probably all you
113       need to know to use Exporter.
114

Advanced Features

116   Specialised Import Lists
117       If any of the entries in an import list begins with !, : or / then the
118       list is treated as a series of specifications which either add to or
119       delete from the list of names to import.  They are processed left to
120       right. Specifications are in the form:
121
122           [!]name         This name only
123           [!]:DEFAULT     All names in @EXPORT
124           [!]:tag         All names in $EXPORT_TAGS{tag} anonymous array
125           [!]/pattern/    All names in @EXPORT and @EXPORT_OK which match
126
127       A leading ! indicates that matching names should be deleted from the
128       list of names to import.  If the first specification is a deletion it
129       is treated as though preceded by :DEFAULT.  If you just want to import
130       extra names in addition to the default set you will still need to
131       include :DEFAULT explicitly.
132
133       e.g., Module.pm defines:
134
135           our @EXPORT      = qw(A1 A2 A3 A4 A5);
136           our @EXPORT_OK   = qw(B1 B2 B3 B4 B5);
137           our %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
138
139       Note that you cannot use tags in @EXPORT or @EXPORT_OK.
140
141       Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK.
142
143       An application using Module can say something like:
144
145           use Module qw(:DEFAULT :T2 !B3 A3);
146
147       Other examples include:
148
149           use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
150           use POSIX  qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
151
152       Remember that most patterns (using //) will need to be anchored with a
153       leading ^, e.g., "/^EXIT/" rather than "/EXIT/".
154
155       You can say "BEGIN { $Exporter::Verbose=1 }" to see how the
156       specifications are being processed and what is actually being imported
157       into modules.
158
159   Exporting Without Using Exporter's import Method
160       Exporter has a special method, 'export_to_level' which is used in
161       situations where you can't directly call Exporter's import method.  The
162       export_to_level method looks like:
163
164           MyPackage->export_to_level(
165               $where_to_export, $package, @what_to_export
166           );
167
168       where $where_to_export is an integer telling how far up the calling
169       stack to export your symbols, and @what_to_export is an array telling
170       what symbols *to* export (usually this is @_).  The $package argument
171       is currently unused.
172
173       For example, suppose that you have a module, A, which already has an
174       import function:
175
176           package A;
177
178           our @ISA = qw(Exporter);
179           our @EXPORT_OK = qw($b);
180
181           sub import
182           {
183               $A::b = 1;     # not a very useful import method
184           }
185
186       and you want to Export symbol $A::b back to the module that called
187       package A.  Since Exporter relies on the import method to work, via
188       inheritance, as it stands Exporter::import() will never get called.
189       Instead, say the following:
190
191           package A;
192           our @ISA = qw(Exporter);
193           our @EXPORT_OK = qw($b);
194
195           sub import
196           {
197               $A::b = 1;
198               A->export_to_level(1, @_);
199           }
200
201       This will export the symbols one level 'above' the current package -
202       ie: to the program or module that used package A.
203
204       Note: Be careful not to modify @_ at all before you call
205       export_to_level - or people using your package will get very
206       unexplained results!
207
208   Exporting Without Inheriting from Exporter
209       By including Exporter in your @ISA you inherit an Exporter's import()
210       method but you also inherit several other helper methods which you
211       probably don't want and complicate the inheritance tree.  To avoid this
212       you can do:
213
214         package YourModule;
215         use Exporter qw(import);
216
217       which will export Exporter's own import() method into YourModule.
218       Everything will work as before but you won't need to include Exporter
219       in @YourModule::ISA.
220
221       Note: This feature was introduced in version 5.57 of Exporter, released
222       with perl 5.8.3.
223
224   Module Version Checking
225       The Exporter module will convert an attempt to import a number from a
226       module into a call to "$module_name->VERSION($value)".  This can be
227       used to validate that the version of the module being used is greater
228       than or equal to the required version.
229
230       For historical reasons, Exporter supplies a "require_version" method
231       that simply delegates to "VERSION".  Originally, before
232       "UNIVERSAL::VERSION" existed, Exporter would call "require_version".
233
234       Since the "UNIVERSAL::VERSION" method treats the $VERSION number as a
235       simple numeric value it will regard version 1.10 as lower than 1.9.
236       For this reason it is strongly recommended that you use numbers with at
237       least two decimal places, e.g., 1.09.
238
239   Managing Unknown Symbols
240       In some situations you may want to prevent certain symbols from being
241       exported.  Typically this applies to extensions which have functions or
242       constants that may not exist on some systems.
243
244       The names of any symbols that cannot be exported should be listed in
245       the @EXPORT_FAIL array.
246
247       If a module attempts to import any of these symbols the Exporter will
248       give the module an opportunity to handle the situation before
249       generating an error.  The Exporter will call an export_fail method with
250       a list of the failed symbols:
251
252         @failed_symbols = $module_name->export_fail(@failed_symbols);
253
254       If the "export_fail" method returns an empty list then no error is
255       recorded and all the requested symbols are exported.  If the returned
256       list is not empty then an error is generated for each symbol and the
257       export fails.  The Exporter provides a default "export_fail" method
258       which simply returns the list unchanged.
259
260       Uses for the "export_fail" method include giving better error messages
261       for some symbols and performing lazy architectural checks (put more
262       symbols into @EXPORT_FAIL by default and then take them out if someone
263       actually tries to use them and an expensive check shows that they are
264       usable on that platform).
265
266   Tag Handling Utility Functions
267       Since the symbols listed within %EXPORT_TAGS must also appear in either
268       @EXPORT or @EXPORT_OK, two utility functions are provided which allow
269       you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK:
270
271         our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
272
273         Exporter::export_tags('foo');     # add aa, bb and cc to @EXPORT
274         Exporter::export_ok_tags('bar');  # add aa, cc and dd to @EXPORT_OK
275
276       Any names which are not tags are added to @EXPORT or @EXPORT_OK
277       unchanged but will trigger a warning (with "-w") to avoid misspelt tags
278       names being silently added to @EXPORT or @EXPORT_OK.  Future versions
279       may make this a fatal error.
280
281   Generating Combined Tags
282       If several symbol categories exist in %EXPORT_TAGS, it's usually useful
283       to create the utility ":all" to simplify "use" statements.
284
285       The simplest way to do this is:
286
287        our  %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
288
289         # add all the other ":class" tags to the ":all" class,
290         # deleting duplicates
291         {
292           my %seen;
293
294           push @{$EXPORT_TAGS{all}},
295             grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
296         }
297
298       CGI.pm creates an ":all" tag which contains some (but not really all)
299       of its categories.  That could be done with one small change:
300
301         # add some of the other ":class" tags to the ":all" class,
302         # deleting duplicates
303         {
304           my %seen;
305
306           push @{$EXPORT_TAGS{all}},
307             grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
308               foreach qw/html2 html3 netscape form cgi internal/;
309         }
310
311       Note that the tag names in %EXPORT_TAGS don't have the leading ':'.
312
313   "AUTOLOAD"ed Constants
314       Many modules make use of "AUTOLOAD"ing for constant subroutines to
315       avoid having to compile and waste memory on rarely used values (see
316       perlsub for details on constant subroutines).  Calls to such constant
317       subroutines are not optimized away at compile time because they can't
318       be checked at compile time for constancy.
319
320       Even if a prototype is available at compile time, the body of the
321       subroutine is not (it hasn't been "AUTOLOAD"ed yet).  perl needs to
322       examine both the "()" prototype and the body of a subroutine at compile
323       time to detect that it can safely replace calls to that subroutine with
324       the constant value.
325
326       A workaround for this is to call the constants once in a "BEGIN" block:
327
328          package My ;
329
330          use Socket ;
331
332          foo( SO_LINGER );  ## SO_LINGER NOT optimized away; called at runtime
333          BEGIN { SO_LINGER }
334          foo( SO_LINGER );  ## SO_LINGER optimized away at compile time.
335
336       This forces the "AUTOLOAD" for "SO_LINGER" to take place before
337       SO_LINGER is encountered later in "My" package.
338
339       If you are writing a package that "AUTOLOAD"s, consider forcing an
340       "AUTOLOAD" for any constants explicitly imported by other packages or
341       which are usually used when your package is "use"d.
342

Good Practices

344   Declaring @EXPORT_OK and Friends
345       When using "Exporter" with the standard "strict" and "warnings"
346       pragmas, the "our" keyword is needed to declare the package variables
347       @EXPORT_OK, @EXPORT, @ISA, etc.
348
349         our @ISA = qw(Exporter);
350         our @EXPORT_OK = qw(munge frobnicate);
351
352       If backward compatibility for Perls under 5.6 is important, one must
353       write instead a "use vars" statement.
354
355         use vars qw(@ISA @EXPORT_OK);
356         @ISA = qw(Exporter);
357         @EXPORT_OK = qw(munge frobnicate);
358
359   Playing Safe
360       There are some caveats with the use of runtime statements like "require
361       Exporter" and the assignment to package variables, which can be very
362       subtle for the unaware programmer.  This may happen for instance with
363       mutually recursive modules, which are affected by the time the relevant
364       constructions are executed.
365
366       The ideal way to never have to think about that is to use "BEGIN"
367       blocks and the simple import method.  So the first part of the
368       "SYNOPSIS" code could be rewritten as:
369
370         package YourModule;
371
372         use strict;
373         use warnings;
374
375         use Exporter 'import';
376         BEGIN {
377           our @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
378         }
379
380       Or if you need to inherit from Exporter:
381
382         package YourModule;
383
384         use strict;
385         use warnings;
386
387         BEGIN {
388           require Exporter;
389           our @ISA = qw(Exporter);  # inherit all of Exporter's methods
390           our @EXPORT_OK = qw(munge frobnicate);  # symbols to export on request
391         }
392
393       The "BEGIN" will assure that the loading of Exporter.pm and the
394       assignments to @ISA and @EXPORT_OK happen immediately like "use",
395       leaving no room for something to get awry or just plain wrong.
396
397       With respect to loading "Exporter" and inheriting, there are
398       alternatives with the use of modules like "base" and "parent".
399
400         use base qw(Exporter);
401         # or
402         use parent qw(Exporter);
403
404       Any of these statements are nice replacements for "BEGIN { require
405       Exporter; our @ISA = qw(Exporter); }" with the same compile-time
406       effect.  The basic difference is that "base" code interacts with
407       declared "fields" while "parent" is a streamlined version of the older
408       "base" code to just establish the IS-A relationship.
409
410       For more details, see the documentation and code of base and parent.
411
412       Another thorough remedy to that runtime vs. compile-time trap is to use
413       Exporter::Easy, which is a wrapper of Exporter that allows all
414       boilerplate code at a single gulp in the use statement.
415
416          use Exporter::Easy (
417              OK => [ qw(munge frobnicate) ],
418          );
419          # @ISA setup is automatic
420          # all assignments happen at compile time
421
422   What Not to Export
423       You have been warned already in "Selecting What to Export" to not
424       export:
425
426       •   method names (because you don't need to and that's likely to not do
427           what you want),
428
429       •   anything by default (because you don't want to surprise your
430           users...  badly)
431
432       •   anything you don't need to (because less is more)
433
434       There's one more item to add to this list.  Do not export variable
435       names.  Just because "Exporter" lets you do that, it does not mean you
436       should.
437
438         @EXPORT_OK = qw($svar @avar %hvar); # DON'T!
439
440       Exporting variables is not a good idea.  They can change under the
441       hood, provoking horrible effects at-a-distance that are too hard to
442       track and to fix.  Trust me: they are not worth it.
443
444       To provide the capability to set/get class-wide settings, it is best
445       instead to provide accessors as subroutines or class methods instead.
446

LICENSE

461       This library is free software.  You can redistribute it and/or modify
462       it under the same terms as Perl itself.
463
464
465
466perl v5.38.0                      2023-07-20                       Exporter(3)

NAME

SYNOPSIS

DESCRIPTION

Advanced Features

Good Practices

SEE ALSO

LICENSE