+Uses for the C<export_fail> method include giving better error messages
+for some symbols and performing lazy architectural checks (put more
+symbols into C<@EXPORT_FAIL> by default and then take them out if someone
+actually tries to use them and an expensive check shows that they are
+usable on that platform).
+
+=head2 Tag Handling Utility Functions
+
+Since the symbols listed within C<%EXPORT_TAGS> must also appear in either
+C<@EXPORT> or C<@EXPORT_OK>, two utility functions are provided which allow
+you to easily add tagged sets of symbols to C<@EXPORT> or C<@EXPORT_OK>:
+
+ %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
+
+ Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT
+ Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK
+
+Any names which are not tags are added to C<@EXPORT> or C<@EXPORT_OK>
+unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags
+names being silently added to C<@EXPORT> or C<@EXPORT_OK>. Future versions
+may make this a fatal error.
+
+=head2 Generating combined tags
+
+If several symbol categories exist in C<%EXPORT_TAGS>, it's usually
+useful to create the utility ":all" to simplify "use" statements.
+
+The simplest way to do this is:
+
+ %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]);
+
+ # add all the other ":class" tags to the ":all" class,
+ # deleting duplicates
+ {
+ my %seen;
+
+ push @{$EXPORT_TAGS{all}},
+ grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS;
+ }
+
+F<CGI.pm> creates an ":all" tag which contains some (but not really
+all) of its categories. That could be done with one small
+change:
+
+ # add some of the other ":class" tags to the ":all" class,
+ # deleting duplicates
+ {
+ my %seen;
+
+ push @{$EXPORT_TAGS{all}},
+ grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}}
+ foreach qw/html2 html3 netscape form cgi internal/;
+ }
+
+Note that the tag names in C<%EXPORT_TAGS> don't have the leading ':'.
+
+=head2 C<AUTOLOAD>ed Constants
+
+Many modules make use of C<AUTOLOAD>ing for constant subroutines to
+avoid having to compile and waste memory on rarely used values (see
+L<perlsub> for details on constant subroutines). Calls to such
+constant subroutines are not optimized away at compile time because
+they can't be checked at compile time for constancy.
+
+Even if a prototype is available at compile time, the body of the
+subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to
+examine both the C<()> prototype and the body of a subroutine at
+compile time to detect that it can safely replace calls to that
+subroutine with the constant value.
+
+A workaround for this is to call the constants once in a C<BEGIN> block:
+
+ package My ;
+
+ use Socket ;
+
+ foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime
+ BEGIN { SO_LINGER }
+ foo( SO_LINGER ); ## SO_LINGER optimized away at compile time.
+
+This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before
+SO_LINGER is encountered later in C<My> package.
+
+If you are writing a package that C<AUTOLOAD>s, consider forcing
+an C<AUTOLOAD> for any constants explicitly imported by other packages
+or which are usually used when your package is C<use>d.
+
+=head1 Good Practices
+
+=head2 Declaring C<@EXPORT_OK> and Friends
+
+When using C<Exporter> with the standard C<strict> and C<warnings>
+pragmas, the C<our> keyword is needed to declare the package
+variables C<@EXPORT_OK>, C<@EXPORT>, C<@ISA>, etc.
+
+ our @ISA = qw(Exporter);
+ our @EXPORT_OK = qw(munge frobnicate);
+
+If backward compatibility for Perls under 5.6 is important,
+one must write instead a C<use vars> statement.
+
+ use vars qw(@ISA @EXPORT_OK);
+ @ISA = qw(Exporter);
+ @EXPORT_OK = qw(munge frobnicate);
+
+=head2 Playing Safe
+
+There are some caveats with the use of runtime statements
+like C<require Exporter> and the assignment to package
+variables, which can very subtle for the unaware programmer.
+This may happen for instance with mutually recursive
+modules, which are affected by the time the relevant
+constructions are executed.
+
+The ideal (but a bit ugly) way to never have to think
+about that is to use C<BEGIN> blocks. So the first part
+of the L</SYNOPSIS> code could be rewritten as:
+
+ package YourModule;
+
+ use strict;
+ use warnings;
+
+ our (@ISA, @EXPORT_OK);
+ BEGIN {
+ require Exporter;
+ @ISA = qw(Exporter);
+ @EXPORT_OK = qw(munge frobnicate); # symbols to export on request
+ }
+
+The C<BEGIN> will assure that the loading of F<Exporter.pm>
+and the assignments to C<@ISA> and C<@EXPORT_OK> happen
+immediately, leaving no room for something to get awry
+or just plain wrong.
+
+With respect to loading C<Exporter> and inheriting, there
+are alternatives with the use of modules like C<base> and C<parent>.
+
+ use base qw( Exporter );
+ # or
+ use parent qw( Exporter );
+
+Any of these statements are nice replacements for
+C<BEGIN { require Exporter; @ISA = qw(Exporter); }>
+with the same compile-time effect. The basic difference
+is that C<base> code interacts with declared C<fields>
+while C<parent> is a streamlined version of the older
+C<base> code to just establish the IS-A relationship.
+
+For more details, see the documentation and code of
+L<base> and L<parent>.
+
+Another thorough remedy to that runtime
+vs. compile-time trap is to use L<Exporter::Easy>,
+which is a wrapper of Exporter that allows all
+boilerplate code at a single gulp in the
+use statement.
+
+ use Exporter::Easy (
+ OK => [ qw(munge frobnicate) ],
+ );
+ # @ISA setup is automatic
+ # all assignments happen at compile time
+
+=head2 What not to Export
+
+You have been warned already in L</Selecting What To Export>
+to not export:
+
+=over 4
+
+=item *
+
+method names (because you don't need to
+and that's likely to not do what you want),
+
+=item *
+
+anything by default (because you don't want to surprise your users...
+badly)
+
+=item *
+
+anything you don't need to (because less is more)
+
+=back
+
+There's one more item to add to this list. Do B<not>
+export variable names. Just because C<Exporter> lets you
+do that, it does not mean you should.
+
+ @EXPORT_OK = qw( $svar @avar %hvar ); # DON'T!
+
+Exporting variables is not a good idea. They can
+change under the hood, provoking horrible
+effects at-a-distance, that are too hard to track
+and to fix. Trust me: they are not worth it.
+
+To provide the capability to set/get class-wide
+settings, it is best instead to provide accessors
+as subroutines or class methods instead.
+
+=head1 SEE ALSO
+
+C<Exporter> is definitely not the only module with
+symbol exporter capabilities. At CPAN, you may find
+a bunch of them. Some are lighter. Some
+provide improved APIs and features. Peek the one
+that fits your needs. The following is
+a sample list of such modules.
+
+ Exporter::Easy
+ Exporter::Lite
+ Exporter::Renaming
+ Exporter::Tidy
+ Sub::Exporter / Sub::Installer
+ Perl6::Export / Perl6::Export::Attrs
+
+=head1 LICENSE
+
+This library is free software. You can redistribute it
+and/or modify it under the same terms as Perl itself.
+
+=cut
https://perl5.git.perl.org / perl5.git / blobdiff