Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Exporter.3pm

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