| 1 | package Exporter; |
| 2 | |
| 3 | require 5.001; |
| 4 | |
| 5 | $ExportLevel = 0; |
| 6 | $Verbose ||= 0; |
| 7 | $VERSION = '5.562'; |
| 8 | |
| 9 | sub export_to_level { |
| 10 | require Exporter::Heavy; |
| 11 | goto &heavy_export_to_level; |
| 12 | } |
| 13 | |
| 14 | sub export { |
| 15 | require Exporter::Heavy; |
| 16 | goto &heavy_export; |
| 17 | } |
| 18 | |
| 19 | sub export_tags { |
| 20 | require Exporter::Heavy; |
| 21 | _push_tags((caller)[0], "EXPORT", \@_); |
| 22 | } |
| 23 | |
| 24 | sub export_ok_tags { |
| 25 | require Exporter::Heavy; |
| 26 | _push_tags((caller)[0], "EXPORT_OK", \@_); |
| 27 | } |
| 28 | |
| 29 | sub import { |
| 30 | my $pkg = shift; |
| 31 | my $callpkg = caller($ExportLevel); |
| 32 | *exports = *{"$pkg\::EXPORT"}; |
| 33 | # We *need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-( |
| 34 | *fail = *{"$pkg\::EXPORT_FAIL"}; |
| 35 | return export $pkg, $callpkg, @_ |
| 36 | if $Verbose or $Debug or @fail > 1; |
| 37 | my $args = @_ or @_ = @exports; |
| 38 | |
| 39 | if ($args and not %exports) { |
| 40 | foreach my $sym (@exports, @{"$pkg\::EXPORT_OK"}) { |
| 41 | $sym =~ s/^&//; |
| 42 | $exports{$sym} = 1; |
| 43 | } |
| 44 | } |
| 45 | if ($Verbose or $Debug |
| 46 | or grep {/\W/ or $args and not exists $exports{$_} |
| 47 | or @fail and $_ eq $fail[0] |
| 48 | or (@{"$pkg\::EXPORT_OK"} |
| 49 | and $_ eq ${"$pkg\::EXPORT_OK"}[0])} @_) { |
| 50 | return export $pkg, $callpkg, ($args ? @_ : ()); |
| 51 | } |
| 52 | #local $SIG{__WARN__} = sub {require Carp; goto &Carp::carp}; |
| 53 | local $SIG{__WARN__} = |
| 54 | sub {require Carp; local $Carp::CarpLevel = 1; &Carp::carp}; |
| 55 | foreach $sym (@_) { |
| 56 | # shortcut for the common case of no type character |
| 57 | *{"$callpkg\::$sym"} = \&{"$pkg\::$sym"}; |
| 58 | } |
| 59 | } |
| 60 | |
| 61 | 1; |
| 62 | |
| 63 | # A simple self test harness. Change 'require Carp' to 'use Carp ()' for testing. |
| 64 | # package main; eval(join('',<DATA>)) or die $@ unless caller; |
| 65 | __END__ |
| 66 | package Test; |
| 67 | $INC{'Exporter.pm'} = 1; |
| 68 | @ISA = qw(Exporter); |
| 69 | @EXPORT = qw(A1 A2 A3 A4 A5); |
| 70 | @EXPORT_OK = qw(B1 B2 B3 B4 B5); |
| 71 | %EXPORT_TAGS = (T1=>[qw(A1 A2 B1 B2)], T2=>[qw(A1 A2 B3 B4)], T3=>[qw(X3)]); |
| 72 | @EXPORT_FAIL = qw(B4); |
| 73 | Exporter::export_ok_tags('T3', 'unknown_tag'); |
| 74 | sub export_fail { |
| 75 | map { "Test::$_" } @_ # edit symbols just as an example |
| 76 | } |
| 77 | |
| 78 | package main; |
| 79 | $Exporter::Verbose = 1; |
| 80 | #import Test; |
| 81 | #import Test qw(X3); # export ok via export_ok_tags() |
| 82 | #import Test qw(:T1 !A2 /5/ !/3/ B5); |
| 83 | import Test qw(:T2 !B4); |
| 84 | import Test qw(:T2); # should fail |
| 85 | 1; |
| 86 | |
| 87 | =head1 NAME |
| 88 | |
| 89 | Exporter - Implements default import method for modules |
| 90 | |
| 91 | =head1 SYNOPSIS |
| 92 | |
| 93 | In module ModuleName.pm: |
| 94 | |
| 95 | package ModuleName; |
| 96 | require Exporter; |
| 97 | @ISA = qw(Exporter); |
| 98 | |
| 99 | @EXPORT = qw(...); # symbols to export by default |
| 100 | @EXPORT_OK = qw(...); # symbols to export on request |
| 101 | %EXPORT_TAGS = tag => [...]; # define names for sets of symbols |
| 102 | |
| 103 | In other files which wish to use ModuleName: |
| 104 | |
| 105 | use ModuleName; # import default symbols into my package |
| 106 | |
| 107 | use ModuleName qw(...); # import listed symbols into my package |
| 108 | |
| 109 | use ModuleName (); # do not import any symbols |
| 110 | |
| 111 | =head1 DESCRIPTION |
| 112 | |
| 113 | The Exporter module implements a default C<import> method which |
| 114 | many modules choose to inherit rather than implement their own. |
| 115 | |
| 116 | Perl automatically calls the C<import> method when processing a |
| 117 | C<use> statement for a module. Modules and C<use> are documented |
| 118 | in L<perlfunc> and L<perlmod>. Understanding the concept of |
| 119 | modules and how the C<use> statement operates is important to |
| 120 | understanding the Exporter. |
| 121 | |
| 122 | =head2 How to Export |
| 123 | |
| 124 | The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of |
| 125 | symbols that are going to be exported into the users name space by |
| 126 | default, or which they can request to be exported, respectively. The |
| 127 | symbols can represent functions, scalars, arrays, hashes, or typeglobs. |
| 128 | The symbols must be given by full name with the exception that the |
| 129 | ampersand in front of a function is optional, e.g. |
| 130 | |
| 131 | @EXPORT = qw(afunc $scalar @array); # afunc is a function |
| 132 | @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc |
| 133 | |
| 134 | =head2 Selecting What To Export |
| 135 | |
| 136 | Do B<not> export method names! |
| 137 | |
| 138 | Do B<not> export anything else by default without a good reason! |
| 139 | |
| 140 | Exports pollute the namespace of the module user. If you must export |
| 141 | try to use @EXPORT_OK in preference to @EXPORT and avoid short or |
| 142 | common symbol names to reduce the risk of name clashes. |
| 143 | |
| 144 | Generally anything not exported is still accessible from outside the |
| 145 | module using the ModuleName::item_name (or $blessed_ref-E<gt>method) |
| 146 | syntax. By convention you can use a leading underscore on names to |
| 147 | informally indicate that they are 'internal' and not for public use. |
| 148 | |
| 149 | (It is actually possible to get private functions by saying: |
| 150 | |
| 151 | my $subref = sub { ... }; |
| 152 | &$subref; |
| 153 | |
| 154 | But there's no way to call that directly as a method, since a method |
| 155 | must have a name in the symbol table.) |
| 156 | |
| 157 | As a general rule, if the module is trying to be object oriented |
| 158 | then export nothing. If it's just a collection of functions then |
| 159 | @EXPORT_OK anything but use @EXPORT with caution. |
| 160 | |
| 161 | Other module design guidelines can be found in L<perlmod>. |
| 162 | |
| 163 | =head2 Specialised Import Lists |
| 164 | |
| 165 | If the first entry in an import list begins with !, : or / then the |
| 166 | list is treated as a series of specifications which either add to or |
| 167 | delete from the list of names to import. They are processed left to |
| 168 | right. Specifications are in the form: |
| 169 | |
| 170 | [!]name This name only |
| 171 | [!]:DEFAULT All names in @EXPORT |
| 172 | [!]:tag All names in $EXPORT_TAGS{tag} anonymous list |
| 173 | [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match |
| 174 | |
| 175 | A leading ! indicates that matching names should be deleted from the |
| 176 | list of names to import. If the first specification is a deletion it |
| 177 | is treated as though preceded by :DEFAULT. If you just want to import |
| 178 | extra names in addition to the default set you will still need to |
| 179 | include :DEFAULT explicitly. |
| 180 | |
| 181 | e.g., Module.pm defines: |
| 182 | |
| 183 | @EXPORT = qw(A1 A2 A3 A4 A5); |
| 184 | @EXPORT_OK = qw(B1 B2 B3 B4 B5); |
| 185 | %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]); |
| 186 | |
| 187 | Note that you cannot use tags in @EXPORT or @EXPORT_OK. |
| 188 | Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK. |
| 189 | |
| 190 | An application using Module can say something like: |
| 191 | |
| 192 | use Module qw(:DEFAULT :T2 !B3 A3); |
| 193 | |
| 194 | Other examples include: |
| 195 | |
| 196 | use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET); |
| 197 | use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/); |
| 198 | |
| 199 | Remember that most patterns (using //) will need to be anchored |
| 200 | with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>. |
| 201 | |
| 202 | You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the |
| 203 | specifications are being processed and what is actually being imported |
| 204 | into modules. |
| 205 | |
| 206 | =head2 Exporting without using Export's import method |
| 207 | |
| 208 | Exporter has a special method, 'export_to_level' which is used in situations |
| 209 | where you can't directly call Export's import method. The export_to_level |
| 210 | method looks like: |
| 211 | |
| 212 | MyPackage->export_to_level($where_to_export, $package, @what_to_export); |
| 213 | |
| 214 | where $where_to_export is an integer telling how far up the calling stack |
| 215 | to export your symbols, and @what_to_export is an array telling what |
| 216 | symbols *to* export (usually this is @_). The $package argument is |
| 217 | currently unused. |
| 218 | |
| 219 | For example, suppose that you have a module, A, which already has an |
| 220 | import function: |
| 221 | |
| 222 | package A; |
| 223 | |
| 224 | @ISA = qw(Exporter); |
| 225 | @EXPORT_OK = qw ($b); |
| 226 | |
| 227 | sub import |
| 228 | { |
| 229 | $A::b = 1; # not a very useful import method |
| 230 | } |
| 231 | |
| 232 | and you want to Export symbol $A::b back to the module that called |
| 233 | package A. Since Exporter relies on the import method to work, via |
| 234 | inheritance, as it stands Exporter::import() will never get called. |
| 235 | Instead, say the following: |
| 236 | |
| 237 | package A; |
| 238 | @ISA = qw(Exporter); |
| 239 | @EXPORT_OK = qw ($b); |
| 240 | |
| 241 | sub import |
| 242 | { |
| 243 | $A::b = 1; |
| 244 | A->export_to_level(1, @_); |
| 245 | } |
| 246 | |
| 247 | This will export the symbols one level 'above' the current package - ie: to |
| 248 | the program or module that used package A. |
| 249 | |
| 250 | Note: Be careful not to modify '@_' at all before you call export_to_level |
| 251 | - or people using your package will get very unexplained results! |
| 252 | |
| 253 | |
| 254 | =head2 Module Version Checking |
| 255 | |
| 256 | The Exporter module will convert an attempt to import a number from a |
| 257 | module into a call to $module_name-E<gt>require_version($value). This can |
| 258 | be used to validate that the version of the module being used is |
| 259 | greater than or equal to the required version. |
| 260 | |
| 261 | The Exporter module supplies a default require_version method which |
| 262 | checks the value of $VERSION in the exporting module. |
| 263 | |
| 264 | Since the default require_version method treats the $VERSION number as |
| 265 | a simple numeric value it will regard version 1.10 as lower than |
| 266 | 1.9. For this reason it is strongly recommended that you use numbers |
| 267 | with at least two decimal places, e.g., 1.09. |
| 268 | |
| 269 | =head2 Managing Unknown Symbols |
| 270 | |
| 271 | In some situations you may want to prevent certain symbols from being |
| 272 | exported. Typically this applies to extensions which have functions |
| 273 | or constants that may not exist on some systems. |
| 274 | |
| 275 | The names of any symbols that cannot be exported should be listed |
| 276 | in the C<@EXPORT_FAIL> array. |
| 277 | |
| 278 | If a module attempts to import any of these symbols the Exporter |
| 279 | will give the module an opportunity to handle the situation before |
| 280 | generating an error. The Exporter will call an export_fail method |
| 281 | with a list of the failed symbols: |
| 282 | |
| 283 | @failed_symbols = $module_name->export_fail(@failed_symbols); |
| 284 | |
| 285 | If the export_fail method returns an empty list then no error is |
| 286 | recorded and all the requested symbols are exported. If the returned |
| 287 | list is not empty then an error is generated for each symbol and the |
| 288 | export fails. The Exporter provides a default export_fail method which |
| 289 | simply returns the list unchanged. |
| 290 | |
| 291 | Uses for the export_fail method include giving better error messages |
| 292 | for some symbols and performing lazy architectural checks (put more |
| 293 | symbols into @EXPORT_FAIL by default and then take them out if someone |
| 294 | actually tries to use them and an expensive check shows that they are |
| 295 | usable on that platform). |
| 296 | |
| 297 | =head2 Tag Handling Utility Functions |
| 298 | |
| 299 | Since the symbols listed within %EXPORT_TAGS must also appear in either |
| 300 | @EXPORT or @EXPORT_OK, two utility functions are provided which allow |
| 301 | you to easily add tagged sets of symbols to @EXPORT or @EXPORT_OK: |
| 302 | |
| 303 | %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); |
| 304 | |
| 305 | Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT |
| 306 | Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK |
| 307 | |
| 308 | Any names which are not tags are added to @EXPORT or @EXPORT_OK |
| 309 | unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags |
| 310 | names being silently added to @EXPORT or @EXPORT_OK. Future versions |
| 311 | may make this a fatal error. |
| 312 | |
| 313 | =cut |