Debian Codegraph @

upstream/debian-unstable/man3/Exporter.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Exporter 3perl"
58 .TH Exporter 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Exporter \- Implements default import method for modules
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 In module \fIYourModule.pm\fR:
68 .PP
69 .Vb 3
70 \& package YourModule;
71 \& use Exporter \*(Aqimport\*(Aq;
72 \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
73 .Ve
74 .PP
75 or
76 .PP
77 .Vb 4
78 \& package YourModule;
79 \& require Exporter;
80 \& our @ISA = qw(Exporter); # inherit all of Exporter\*(Aqs methods
81 \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
82 .Ve
83 .PP
84 or
85 .PP
86 .Vb 3
87 \& package YourModule;
88 \& use parent \*(AqExporter\*(Aq; # inherit all of Exporter\*(Aqs methods
89 \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
90 .Ve
91 .PP
92 In other files which wish to use \f(CW\*(C`YourModule\*(C'\fR:
93 .PP
94 .Vb 2
95 \& use YourModule qw(frobnicate); # import listed symbols
96 \& frobnicate ($left, $right) # calls YourModule::frobnicate
97 .Ve
98 .PP
99 Take a look at "Good Practices" for some variants
100 you will like to use in modern Perl code.
101 .SH DESCRIPTION
102 .IX Header "DESCRIPTION"
103 The Exporter module implements an \f(CW\*(C`import\*(C'\fR method which allows a module
104 to export functions and variables to its users' namespaces. Many modules
105 use Exporter rather than implementing their own \f(CW\*(C`import\*(C'\fR method because
106 Exporter provides a highly flexible interface, with an implementation optimised
107 for the common case.
108 .PP
109 Perl automatically calls the \f(CW\*(C`import\*(C'\fR method when processing a
110 \&\f(CW\*(C`use\*(C'\fR statement for a module. Modules and \f(CW\*(C`use\*(C'\fR are documented
111 in perlfunc and perlmod. Understanding the concept of
112 modules and how the \f(CW\*(C`use\*(C'\fR statement operates is important to
113 understanding the Exporter.
114 .SS "How to Export"
115 .IX Subsection "How to Export"
116 The arrays \f(CW@EXPORT\fR and \f(CW@EXPORT_OK\fR in a module hold lists of
117 symbols that are going to be exported into the users name space by
118 default, or which they can request to be exported, respectively. The
119 symbols can represent functions, scalars, arrays, hashes, or typeglobs.
120 The symbols must be given by full name with the exception that the
121 ampersand in front of a function is optional, e.g.
122 .PP
123 .Vb 2
124 \& our @EXPORT = qw(afunc $scalar @array); # afunc is a function
125 \& our @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc
126 .Ve
127 .PP
128 If you are only exporting function names it is recommended to omit the
129 ampersand, as the implementation is faster this way.
130 .SS "Selecting What to Export"
131 .IX Subsection "Selecting What to Export"
132 Do \fBnot\fR export method names!
133 .PP
134 Do \fBnot\fR export anything else by default without a good reason!
135 .PP
136 Exports pollute the namespace of the module user. If you must export
137 try to use \f(CW@EXPORT_OK\fR in preference to \f(CW@EXPORT\fR and avoid short or
138 common symbol names to reduce the risk of name clashes.
139 .PP
140 Generally anything not exported is still accessible from outside the
141 module using the \f(CW\*(C`YourModule::item_name\*(C'\fR (or \f(CW\*(C`$blessed_ref\->method\*(C'\fR)
142 syntax. By convention you can use a leading underscore on names to
143 informally indicate that they are 'internal' and not for public use.
144 .PP
145 (It is actually possible to get private functions by saying:
146 .PP
147 .Vb 3
148 \& my $subref = sub { ... };
149 \& $subref\->(@args); # Call it as a function
150 \& $obj\->$subref(@args); # Use it as a method
151 .Ve
152 .PP
153 However if you use them for methods it is up to you to figure out
154 how to make inheritance work.)
155 .PP
156 As a general rule, if the module is trying to be object oriented
157 then export nothing. If it's just a collection of functions then
158 \&\f(CW@EXPORT_OK\fR anything but use \f(CW@EXPORT\fR with caution. For function and
159 method names use barewords in preference to names prefixed with
160 ampersands for the export lists.
161 .PP
162 Other module design guidelines can be found in perlmod.
163 .SS "How to Import"
164 .IX Subsection "How to Import"
165 In other files which wish to use your module there are three basic ways for
166 them to load your module and import its symbols:
167 .ie n .IP """use YourModule;""" 4
168 .el .IP "\f(CWuse YourModule;\fR" 4
169 .IX Item "use YourModule;"
170 This imports all the symbols from YourModule's \f(CW@EXPORT\fR into the namespace
171 of the \f(CW\*(C`use\*(C'\fR statement.
172 .ie n .IP """use YourModule ();""" 4
173 .el .IP "\f(CWuse YourModule ();\fR" 4
174 .IX Item "use YourModule ();"
175 This causes perl to load your module but does not import any symbols.
176 .ie n .IP """use YourModule qw(...);""" 4
177 .el .IP "\f(CWuse YourModule qw(...);\fR" 4
178 .IX Item "use YourModule qw(...);"
179 This imports only the symbols listed by the caller into their namespace.
180 All listed symbols must be in your \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR, else an error
181 occurs. The advanced export features of Exporter are accessed like this,
182 but with list entries that are syntactically distinct from symbol names.
183 .PP
184 Unless you want to use its advanced features, this is probably all you
185 need to know to use Exporter.
186 .SH "Advanced Features"
187 .IX Header "Advanced Features"
188 .SS "Specialised Import Lists"
189 .IX Subsection "Specialised Import Lists"
190 If any of the entries in an import list begins with !, : or / then
191 the list is treated as a series of specifications which either add to
192 or delete from the list of names to import. They are processed left to
193 right. Specifications are in the form:
194 .PP
195 .Vb 4
196 \& [!]name This name only
197 \& [!]:DEFAULT All names in @EXPORT
198 \& [!]:tag All names in $EXPORT_TAGS{tag} anonymous array
199 \& [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match
200 .Ve
201 .PP
202 A leading ! indicates that matching names should be deleted from the
203 list of names to import. If the first specification is a deletion it
204 is treated as though preceded by :DEFAULT. If you just want to import
205 extra names in addition to the default set you will still need to
206 include :DEFAULT explicitly.
207 .PP
208 e.g., \fIModule.pm\fR defines:
209 .PP
210 .Vb 3
211 \& our @EXPORT = qw(A1 A2 A3 A4 A5);
212 \& our @EXPORT_OK = qw(B1 B2 B3 B4 B5);
213 \& our %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]);
214 .Ve
215 .PP
216 Note that you cannot use tags in \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR.
217 .PP
218 Names in EXPORT_TAGS must also appear in \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR.
219 .PP
220 An application using Module can say something like:
221 .PP
222 .Vb 1
223 \& use Module qw(:DEFAULT :T2 !B3 A3);
224 .Ve
225 .PP
226 Other examples include:
227 .PP
228 .Vb 2
229 \& use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET);
230 \& use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/);
231 .Ve
232 .PP
233 Remember that most patterns (using //) will need to be anchored
234 with a leading ^, e.g., \f(CW\*(C`/^EXIT/\*(C'\fR rather than \f(CW\*(C`/EXIT/\*(C'\fR.
235 .PP
236 You can say \f(CW\*(C`BEGIN { $Exporter::Verbose=1 }\*(C'\fR to see how the
237 specifications are being processed and what is actually being imported
238 into modules.
239 .SS "Exporting Without Using Exporter's import Method"
240 .IX Subsection "Exporting Without Using Exporter's import Method"
241 Exporter has a special method, 'export_to_level' which is used in situations
242 where you can't directly call Exporter's
243 import method. The export_to_level
244 method looks like:
245 .PP
246 .Vb 3
247 \& MyPackage\->export_to_level(
248 \& $where_to_export, $package, @what_to_export
249 \& );
250 .Ve
251 .PP
252 where \f(CW$where_to_export\fR is an integer telling how far up the calling stack
253 to export your symbols, and \f(CW@what_to_export\fR is an array telling what
254 symbols *to* export (usually this is \f(CW@_\fR). The \f(CW$package\fR argument is
255 currently unused.
256 .PP
257 For example, suppose that you have a module, A, which already has an
258 import function:
259 .PP
260 .Vb 1
261 \& package A;
262 \&
263 \& our @ISA = qw(Exporter);
264 \& our @EXPORT_OK = qw($b);
265 \&
266 \& sub import
267 \& {
268 \& $A::b = 1; # not a very useful import method
269 \& }
270 .Ve
271 .PP
272 and you want to Export symbol \f(CW$A::b\fR back to the module that called
273 package A. Since Exporter relies on the import method to work, via
274 inheritance, as it stands \fBExporter::import()\fR will never get called.
275 Instead, say the following:
276 .PP
277 .Vb 3
278 \& package A;
279 \& our @ISA = qw(Exporter);
280 \& our @EXPORT_OK = qw($b);
281 \&
282 \& sub import
283 \& {
284 \& $A::b = 1;
285 \& A\->export_to_level(1, @_);
286 \& }
287 .Ve
288 .PP
289 This will export the symbols one level 'above' the current package \- ie: to
290 the program or module that used package A.
291 .PP
292 Note: Be careful not to modify \f(CW@_\fR at all before you call export_to_level
293 \&\- or people using your package will get very unexplained results!
294 .SS "Exporting Without Inheriting from Exporter"
295 .IX Subsection "Exporting Without Inheriting from Exporter"
296 By including Exporter in your \f(CW@ISA\fR you inherit an Exporter's \fBimport()\fR method
297 but you also inherit several other helper methods which you probably don't
298 want and complicate the inheritance tree. To avoid this you can do:
299 .PP
300 .Vb 2
301 \& package YourModule;
302 \& use Exporter qw(import);
303 .Ve
304 .PP
305 which will export Exporter's own \fBimport()\fR method into YourModule.
306 Everything will work as before but you won't need to include Exporter in
307 \&\f(CW@YourModule::ISA\fR.
308 .PP
309 Note: This feature was introduced in version 5.57
310 of Exporter, released with perl 5.8.3.
311 .SS "Module Version Checking"
312 .IX Subsection "Module Version Checking"
313 The Exporter module will convert an attempt to import a number from a
314 module into a call to \f(CW\*(C`$module_name\->VERSION($value)\*(C'\fR. This can
315 be used to validate that the version of the module being used is
316 greater than or equal to the required version.
317 .PP
318 For historical reasons, Exporter supplies a \f(CW\*(C`require_version\*(C'\fR method that
319 simply delegates to \f(CW\*(C`VERSION\*(C'\fR. Originally, before \f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR
320 existed, Exporter would call \f(CW\*(C`require_version\*(C'\fR.
321 .PP
322 Since the \f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR method treats the \f(CW$VERSION\fR number as
323 a simple numeric value it will regard version 1.10 as lower than
324 1.9. For this reason it is strongly recommended that you use numbers
325 with at least two decimal places, e.g., 1.09.
326 .SS "Managing Unknown Symbols"
327 .IX Subsection "Managing Unknown Symbols"
328 In some situations you may want to prevent certain symbols from being
329 exported. Typically this applies to extensions which have functions
330 or constants that may not exist on some systems.
331 .PP
332 The names of any symbols that cannot be exported should be listed
333 in the \f(CW@EXPORT_FAIL\fR array.
334 .PP
335 If a module attempts to import any of these symbols the Exporter
336 will give the module an opportunity to handle the situation before
337 generating an error. The Exporter will call an export_fail method
338 with a list of the failed symbols:
339 .PP
340 .Vb 1
341 \& @failed_symbols = $module_name\->export_fail(@failed_symbols);
342 .Ve
343 .PP
344 If the \f(CW\*(C`export_fail\*(C'\fR method returns an empty list then no error is
345 recorded and all the requested symbols are exported. If the returned
346 list is not empty then an error is generated for each symbol and the
347 export fails. The Exporter provides a default \f(CW\*(C`export_fail\*(C'\fR method which
348 simply returns the list unchanged.
349 .PP
350 Uses for the \f(CW\*(C`export_fail\*(C'\fR method include giving better error messages
351 for some symbols and performing lazy architectural checks (put more
352 symbols into \f(CW@EXPORT_FAIL\fR by default and then take them out if someone
353 actually tries to use them and an expensive check shows that they are
354 usable on that platform).
355 .SS "Tag Handling Utility Functions"
356 .IX Subsection "Tag Handling Utility Functions"
357 Since the symbols listed within \f(CW%EXPORT_TAGS\fR must also appear in either
358 \&\f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR, two utility functions are provided which allow
359 you to easily add tagged sets of symbols to \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR:
360 .PP
361 .Vb 1
362 \& our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
363 \&
364 \& Exporter::export_tags(\*(Aqfoo\*(Aq); # add aa, bb and cc to @EXPORT
365 \& Exporter::export_ok_tags(\*(Aqbar\*(Aq); # add aa, cc and dd to @EXPORT_OK
366 .Ve
367 .PP
368 Any names which are not tags are added to \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR
369 unchanged but will trigger a warning (with \f(CW\*(C`\-w\*(C'\fR) to avoid misspelt tags
370 names being silently added to \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR. Future versions
371 may make this a fatal error.
372 .SS "Generating Combined Tags"
373 .IX Subsection "Generating Combined Tags"
374 If several symbol categories exist in \f(CW%EXPORT_TAGS\fR, it's usually
375 useful to create the utility ":all" to simplify "use" statements.
376 .PP
377 The simplest way to do this is:
378 .PP
379 .Vb 1
380 \& our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
381 \&
382 \& # add all the other ":class" tags to the ":all" class,
383 \& # deleting duplicates
384 \& {
385 \& my %seen;
386 \&
387 \& push @{$EXPORT_TAGS{all}},
388 \& grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
389 \& }
390 .Ve
391 .PP
392 \&\fICGI.pm\fR creates an ":all" tag which contains some (but not really
393 all) of its categories. That could be done with one small
394 change:
395 .PP
396 .Vb 4
397 \& # add some of the other ":class" tags to the ":all" class,
398 \& # deleting duplicates
399 \& {
400 \& my %seen;
401 \&
402 \& push @{$EXPORT_TAGS{all}},
403 \& grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
404 \& foreach qw/html2 html3 netscape form cgi internal/;
405 \& }
406 .Ve
407 .PP
408 Note that the tag names in \f(CW%EXPORT_TAGS\fR don't have the leading ':'.
409 .ie n .SS """AUTOLOAD""ed Constants"
410 .el .SS "\f(CWAUTOLOAD\fPed Constants"
411 .IX Subsection "AUTOLOADed Constants"
412 Many modules make use of \f(CW\*(C`AUTOLOAD\*(C'\fRing for constant subroutines to
413 avoid having to compile and waste memory on rarely used values (see
414 perlsub for details on constant subroutines). Calls to such
415 constant subroutines are not optimized away at compile time because
416 they can't be checked at compile time for constancy.
417 .PP
418 Even if a prototype is available at compile time, the body of the
419 subroutine is not (it hasn't been \f(CW\*(C`AUTOLOAD\*(C'\fRed yet). perl needs to
420 examine both the \f(CW\*(C`()\*(C'\fR prototype and the body of a subroutine at
421 compile time to detect that it can safely replace calls to that
422 subroutine with the constant value.
423 .PP
424 A workaround for this is to call the constants once in a \f(CW\*(C`BEGIN\*(C'\fR block:
425 .PP
426 .Vb 1
427 \& package My ;
428 \&
429 \& use Socket ;
430 \&
431 \& foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime
432 \& BEGIN { SO_LINGER }
433 \& foo( SO_LINGER ); ## SO_LINGER optimized away at compile time.
434 .Ve
435 .PP
436 This forces the \f(CW\*(C`AUTOLOAD\*(C'\fR for \f(CW\*(C`SO_LINGER\*(C'\fR to take place before
437 SO_LINGER is encountered later in \f(CW\*(C`My\*(C'\fR package.
438 .PP
439 If you are writing a package that \f(CW\*(C`AUTOLOAD\*(C'\fRs, consider forcing
440 an \f(CW\*(C`AUTOLOAD\*(C'\fR for any constants explicitly imported by other packages
441 or which are usually used when your package is \f(CW\*(C`use\*(C'\fRd.
442 .SH "Good Practices"
443 .IX Header "Good Practices"
444 .ie n .SS "Declaring @EXPORT_OK and Friends"
445 .el .SS "Declaring \f(CW@EXPORT_OK\fP and Friends"
446 .IX Subsection "Declaring @EXPORT_OK and Friends"
447 When using \f(CW\*(C`Exporter\*(C'\fR with the standard \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR
448 pragmas, the \f(CW\*(C`our\*(C'\fR keyword is needed to declare the package
449 variables \f(CW@EXPORT_OK\fR, \f(CW@EXPORT\fR, \f(CW@ISA\fR, etc.
450 .PP
451 .Vb 2
452 \& our @ISA = qw(Exporter);
453 \& our @EXPORT_OK = qw(munge frobnicate);
454 .Ve
455 .PP
456 If backward compatibility for Perls \fBunder\fR 5.6 is important,
457 one must write instead a \f(CW\*(C`use vars\*(C'\fR statement.
458 .PP
459 .Vb 3
460 \& use vars qw(@ISA @EXPORT_OK);
461 \& @ISA = qw(Exporter);
462 \& @EXPORT_OK = qw(munge frobnicate);
463 .Ve
464 .SS "Playing Safe"
465 .IX Subsection "Playing Safe"
466 There are some caveats with the use of runtime statements
467 like \f(CW\*(C`require Exporter\*(C'\fR and the assignment to package
468 variables, which can be very subtle for the unaware programmer.
469 This may happen for instance with mutually recursive
470 modules, which are affected by the time the relevant
471 constructions are executed.
472 .PP
473 The ideal way to never have to think about that is to use
474 \&\f(CW\*(C`BEGIN\*(C'\fR blocks and the simple import method. So the first part
475 of the "SYNOPSIS" code could be rewritten as:
476 .PP
477 .Vb 1
478 \& package YourModule;
479 \&
480 \& use strict;
481 \& use warnings;
482 \&
483 \& use Exporter \*(Aqimport\*(Aq;
484 \& BEGIN {
485 \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
486 \& }
487 .Ve
488 .PP
489 Or if you need to inherit from Exporter:
490 .PP
491 .Vb 1
492 \& package YourModule;
493 \&
494 \& use strict;
495 \& use warnings;
496 \&
497 \& BEGIN {
498 \& require Exporter;
499 \& our @ISA = qw(Exporter); # inherit all of Exporter\*(Aqs methods
500 \& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
501 \& }
502 .Ve
503 .PP
504 The \f(CW\*(C`BEGIN\*(C'\fR will assure that the loading of \fIExporter.pm\fR
505 and the assignments to \f(CW@ISA\fR and \f(CW@EXPORT_OK\fR happen
506 immediately like \f(CW\*(C`use\*(C'\fR, leaving no room for something to get awry
507 or just plain wrong.
508 .PP
509 With respect to loading \f(CW\*(C`Exporter\*(C'\fR and inheriting, there
510 are alternatives with the use of modules like \f(CW\*(C`base\*(C'\fR and \f(CW\*(C`parent\*(C'\fR.
511 .PP
512 .Vb 3
513 \& use base qw(Exporter);
514 \& # or
515 \& use parent qw(Exporter);
516 .Ve
517 .PP
518 Any of these statements are nice replacements for
519 \&\f(CW\*(C`BEGIN { require Exporter; our @ISA = qw(Exporter); }\*(C'\fR
520 with the same compile-time effect. The basic difference
521 is that \f(CW\*(C`base\*(C'\fR code interacts with declared \f(CW\*(C`fields\*(C'\fR
522 while \f(CW\*(C`parent\*(C'\fR is a streamlined version of the older
523 \&\f(CW\*(C`base\*(C'\fR code to just establish the IS-A relationship.
524 .PP
525 For more details, see the documentation and code of
526 base and parent.
527 .PP
528 Another thorough remedy to that runtime
529 vs. compile-time trap is to use Exporter::Easy,
530 which is a wrapper of Exporter that allows all
531 boilerplate code at a single gulp in the
532 use statement.
533 .PP
534 .Vb 5
535 \& use Exporter::Easy (
536 \& OK => [ qw(munge frobnicate) ],
537 \& );
538 \& # @ISA setup is automatic
539 \& # all assignments happen at compile time
540 .Ve
541 .SS "What Not to Export"
542 .IX Subsection "What Not to Export"
543 You have been warned already in "Selecting What to Export"
544 to not export:
545 .IP \(bu 4
546 method names (because you don't need to
547 and that's likely to not do what you want),
548 .IP \(bu 4
549 anything by default (because you don't want to surprise your users...
550 badly)
551 .IP \(bu 4
552 anything you don't need to (because less is more)
553 .PP
554 There's one more item to add to this list. Do \fBnot\fR
555 export variable names. Just because \f(CW\*(C`Exporter\*(C'\fR lets you
556 do that, it does not mean you should.
557 .PP
558 .Vb 1
559 \& @EXPORT_OK = qw($svar @avar %hvar); # DON\*(AqT!
560 .Ve
561 .PP
562 Exporting variables is not a good idea. They can
563 change under the hood, provoking horrible
564 effects at-a-distance that are too hard to track
565 and to fix. Trust me: they are not worth it.
566 .PP
567 To provide the capability to set/get class-wide
568 settings, it is best instead to provide accessors
569 as subroutines or class methods instead.
570 .SH "SEE ALSO"
571 .IX Header "SEE ALSO"
572 \&\f(CW\*(C`Exporter\*(C'\fR is definitely not the only module with
573 symbol exporter capabilities. At CPAN, you may find
574 a bunch of them. Some are lighter. Some
575 provide improved APIs and features. Pick the one
576 that fits your needs. The following is
577 a sample list of such modules.
578 .PP
579 .Vb 6
580 \& Exporter::Easy
581 \& Exporter::Lite
582 \& Exporter::Renaming
583 \& Exporter::Tidy
584 \& Sub::Exporter / Sub::Installer
585 \& Perl6::Export / Perl6::Export::Attrs
586 .Ve
587 .SH LICENSE
588 .IX Header "LICENSE"
589 This library is free software. You can redistribute it
590 and/or modify it under the same terms as Perl itself.