| 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. |