diff options
Diffstat (limited to 'upstream/debian-unstable/man3/Exporter.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/Exporter.3perl | 590 |
1 files changed, 590 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/Exporter.3perl b/upstream/debian-unstable/man3/Exporter.3perl new file mode 100644 index 00000000..217dbc4d --- /dev/null +++ b/upstream/debian-unstable/man3/Exporter.3perl @@ -0,0 +1,590 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Exporter 3perl" +.TH Exporter 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Exporter \- Implements default import method for modules +.SH SYNOPSIS +.IX Header "SYNOPSIS" +In module \fIYourModule.pm\fR: +.PP +.Vb 3 +\& package YourModule; +\& use Exporter \*(Aqimport\*(Aq; +\& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request +.Ve +.PP +or +.PP +.Vb 4 +\& package YourModule; +\& require Exporter; +\& our @ISA = qw(Exporter); # inherit all of Exporter\*(Aqs methods +\& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request +.Ve +.PP +or +.PP +.Vb 3 +\& package YourModule; +\& use parent \*(AqExporter\*(Aq; # inherit all of Exporter\*(Aqs methods +\& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request +.Ve +.PP +In other files which wish to use \f(CW\*(C`YourModule\*(C'\fR: +.PP +.Vb 2 +\& use YourModule qw(frobnicate); # import listed symbols +\& frobnicate ($left, $right) # calls YourModule::frobnicate +.Ve +.PP +Take a look at "Good Practices" for some variants +you will like to use in modern Perl code. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The Exporter module implements an \f(CW\*(C`import\*(C'\fR method which allows a module +to export functions and variables to its users' namespaces. Many modules +use Exporter rather than implementing their own \f(CW\*(C`import\*(C'\fR method because +Exporter provides a highly flexible interface, with an implementation optimised +for the common case. +.PP +Perl automatically calls the \f(CW\*(C`import\*(C'\fR method when processing a +\&\f(CW\*(C`use\*(C'\fR statement for a module. Modules and \f(CW\*(C`use\*(C'\fR are documented +in perlfunc and perlmod. Understanding the concept of +modules and how the \f(CW\*(C`use\*(C'\fR statement operates is important to +understanding the Exporter. +.SS "How to Export" +.IX Subsection "How to Export" +The arrays \f(CW@EXPORT\fR and \f(CW@EXPORT_OK\fR in a module hold lists of +symbols that are going to be exported into the users name space by +default, or which they can request to be exported, respectively. The +symbols can represent functions, scalars, arrays, hashes, or typeglobs. +The symbols must be given by full name with the exception that the +ampersand in front of a function is optional, e.g. +.PP +.Vb 2 +\& our @EXPORT = qw(afunc $scalar @array); # afunc is a function +\& our @EXPORT_OK = qw(&bfunc %hash *typeglob); # explicit prefix on &bfunc +.Ve +.PP +If you are only exporting function names it is recommended to omit the +ampersand, as the implementation is faster this way. +.SS "Selecting What to Export" +.IX Subsection "Selecting What to Export" +Do \fBnot\fR export method names! +.PP +Do \fBnot\fR export anything else by default without a good reason! +.PP +Exports pollute the namespace of the module user. If you must export +try to use \f(CW@EXPORT_OK\fR in preference to \f(CW@EXPORT\fR and avoid short or +common symbol names to reduce the risk of name clashes. +.PP +Generally anything not exported is still accessible from outside the +module using the \f(CW\*(C`YourModule::item_name\*(C'\fR (or \f(CW\*(C`$blessed_ref\->method\*(C'\fR) +syntax. By convention you can use a leading underscore on names to +informally indicate that they are 'internal' and not for public use. +.PP +(It is actually possible to get private functions by saying: +.PP +.Vb 3 +\& my $subref = sub { ... }; +\& $subref\->(@args); # Call it as a function +\& $obj\->$subref(@args); # Use it as a method +.Ve +.PP +However if you use them for methods it is up to you to figure out +how to make inheritance work.) +.PP +As a general rule, if the module is trying to be object oriented +then export nothing. If it's just a collection of functions then +\&\f(CW@EXPORT_OK\fR anything but use \f(CW@EXPORT\fR with caution. For function and +method names use barewords in preference to names prefixed with +ampersands for the export lists. +.PP +Other module design guidelines can be found in perlmod. +.SS "How to Import" +.IX Subsection "How to Import" +In other files which wish to use your module there are three basic ways for +them to load your module and import its symbols: +.ie n .IP """use YourModule;""" 4 +.el .IP "\f(CWuse YourModule;\fR" 4 +.IX Item "use YourModule;" +This imports all the symbols from YourModule's \f(CW@EXPORT\fR into the namespace +of the \f(CW\*(C`use\*(C'\fR statement. +.ie n .IP """use YourModule ();""" 4 +.el .IP "\f(CWuse YourModule ();\fR" 4 +.IX Item "use YourModule ();" +This causes perl to load your module but does not import any symbols. +.ie n .IP """use YourModule qw(...);""" 4 +.el .IP "\f(CWuse YourModule qw(...);\fR" 4 +.IX Item "use YourModule qw(...);" +This imports only the symbols listed by the caller into their namespace. +All listed symbols must be in your \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR, else an error +occurs. The advanced export features of Exporter are accessed like this, +but with list entries that are syntactically distinct from symbol names. +.PP +Unless you want to use its advanced features, this is probably all you +need to know to use Exporter. +.SH "Advanced Features" +.IX Header "Advanced Features" +.SS "Specialised Import Lists" +.IX Subsection "Specialised Import Lists" +If any of the entries in an import list begins with !, : or / then +the list is treated as a series of specifications which either add to +or delete from the list of names to import. They are processed left to +right. Specifications are in the form: +.PP +.Vb 4 +\& [!]name This name only +\& [!]:DEFAULT All names in @EXPORT +\& [!]:tag All names in $EXPORT_TAGS{tag} anonymous array +\& [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match +.Ve +.PP +A leading ! indicates that matching names should be deleted from the +list of names to import. If the first specification is a deletion it +is treated as though preceded by :DEFAULT. If you just want to import +extra names in addition to the default set you will still need to +include :DEFAULT explicitly. +.PP +e.g., \fIModule.pm\fR defines: +.PP +.Vb 3 +\& our @EXPORT = qw(A1 A2 A3 A4 A5); +\& our @EXPORT_OK = qw(B1 B2 B3 B4 B5); +\& our %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]); +.Ve +.PP +Note that you cannot use tags in \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR. +.PP +Names in EXPORT_TAGS must also appear in \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR. +.PP +An application using Module can say something like: +.PP +.Vb 1 +\& use Module qw(:DEFAULT :T2 !B3 A3); +.Ve +.PP +Other examples include: +.PP +.Vb 2 +\& use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET); +\& use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/); +.Ve +.PP +Remember that most patterns (using //) will need to be anchored +with a leading ^, e.g., \f(CW\*(C`/^EXIT/\*(C'\fR rather than \f(CW\*(C`/EXIT/\*(C'\fR. +.PP +You can say \f(CW\*(C`BEGIN { $Exporter::Verbose=1 }\*(C'\fR to see how the +specifications are being processed and what is actually being imported +into modules. +.SS "Exporting Without Using Exporter's import Method" +.IX Subsection "Exporting Without Using Exporter's import Method" +Exporter has a special method, 'export_to_level' which is used in situations +where you can't directly call Exporter's +import method. The export_to_level +method looks like: +.PP +.Vb 3 +\& MyPackage\->export_to_level( +\& $where_to_export, $package, @what_to_export +\& ); +.Ve +.PP +where \f(CW$where_to_export\fR is an integer telling how far up the calling stack +to export your symbols, and \f(CW@what_to_export\fR is an array telling what +symbols *to* export (usually this is \f(CW@_\fR). The \f(CW$package\fR argument is +currently unused. +.PP +For example, suppose that you have a module, A, which already has an +import function: +.PP +.Vb 1 +\& package A; +\& +\& our @ISA = qw(Exporter); +\& our @EXPORT_OK = qw($b); +\& +\& sub import +\& { +\& $A::b = 1; # not a very useful import method +\& } +.Ve +.PP +and you want to Export symbol \f(CW$A::b\fR back to the module that called +package A. Since Exporter relies on the import method to work, via +inheritance, as it stands \fBExporter::import()\fR will never get called. +Instead, say the following: +.PP +.Vb 3 +\& package A; +\& our @ISA = qw(Exporter); +\& our @EXPORT_OK = qw($b); +\& +\& sub import +\& { +\& $A::b = 1; +\& A\->export_to_level(1, @_); +\& } +.Ve +.PP +This will export the symbols one level 'above' the current package \- ie: to +the program or module that used package A. +.PP +Note: Be careful not to modify \f(CW@_\fR at all before you call export_to_level +\&\- or people using your package will get very unexplained results! +.SS "Exporting Without Inheriting from Exporter" +.IX Subsection "Exporting Without Inheriting from Exporter" +By including Exporter in your \f(CW@ISA\fR you inherit an Exporter's \fBimport()\fR method +but you also inherit several other helper methods which you probably don't +want and complicate the inheritance tree. To avoid this you can do: +.PP +.Vb 2 +\& package YourModule; +\& use Exporter qw(import); +.Ve +.PP +which will export Exporter's own \fBimport()\fR method into YourModule. +Everything will work as before but you won't need to include Exporter in +\&\f(CW@YourModule::ISA\fR. +.PP +Note: This feature was introduced in version 5.57 +of Exporter, released with perl 5.8.3. +.SS "Module Version Checking" +.IX Subsection "Module Version Checking" +The Exporter module will convert an attempt to import a number from a +module into a call to \f(CW\*(C`$module_name\->VERSION($value)\*(C'\fR. This can +be used to validate that the version of the module being used is +greater than or equal to the required version. +.PP +For historical reasons, Exporter supplies a \f(CW\*(C`require_version\*(C'\fR method that +simply delegates to \f(CW\*(C`VERSION\*(C'\fR. Originally, before \f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR +existed, Exporter would call \f(CW\*(C`require_version\*(C'\fR. +.PP +Since the \f(CW\*(C`UNIVERSAL::VERSION\*(C'\fR method treats the \f(CW$VERSION\fR number as +a simple numeric value it will regard version 1.10 as lower than +1.9. For this reason it is strongly recommended that you use numbers +with at least two decimal places, e.g., 1.09. +.SS "Managing Unknown Symbols" +.IX Subsection "Managing Unknown Symbols" +In some situations you may want to prevent certain symbols from being +exported. Typically this applies to extensions which have functions +or constants that may not exist on some systems. +.PP +The names of any symbols that cannot be exported should be listed +in the \f(CW@EXPORT_FAIL\fR array. +.PP +If a module attempts to import any of these symbols the Exporter +will give the module an opportunity to handle the situation before +generating an error. The Exporter will call an export_fail method +with a list of the failed symbols: +.PP +.Vb 1 +\& @failed_symbols = $module_name\->export_fail(@failed_symbols); +.Ve +.PP +If the \f(CW\*(C`export_fail\*(C'\fR method returns an empty list then no error is +recorded and all the requested symbols are exported. If the returned +list is not empty then an error is generated for each symbol and the +export fails. The Exporter provides a default \f(CW\*(C`export_fail\*(C'\fR method which +simply returns the list unchanged. +.PP +Uses for the \f(CW\*(C`export_fail\*(C'\fR method include giving better error messages +for some symbols and performing lazy architectural checks (put more +symbols into \f(CW@EXPORT_FAIL\fR 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). +.SS "Tag Handling Utility Functions" +.IX Subsection "Tag Handling Utility Functions" +Since the symbols listed within \f(CW%EXPORT_TAGS\fR must also appear in either +\&\f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR, two utility functions are provided which allow +you to easily add tagged sets of symbols to \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR: +.PP +.Vb 1 +\& our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); +\& +\& Exporter::export_tags(\*(Aqfoo\*(Aq); # add aa, bb and cc to @EXPORT +\& Exporter::export_ok_tags(\*(Aqbar\*(Aq); # add aa, cc and dd to @EXPORT_OK +.Ve +.PP +Any names which are not tags are added to \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR +unchanged but will trigger a warning (with \f(CW\*(C`\-w\*(C'\fR) to avoid misspelt tags +names being silently added to \f(CW@EXPORT\fR or \f(CW@EXPORT_OK\fR. Future versions +may make this a fatal error. +.SS "Generating Combined Tags" +.IX Subsection "Generating Combined Tags" +If several symbol categories exist in \f(CW%EXPORT_TAGS\fR, it's usually +useful to create the utility ":all" to simplify "use" statements. +.PP +The simplest way to do this is: +.PP +.Vb 1 +\& our %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; +\& } +.Ve +.PP +\&\fICGI.pm\fR creates an ":all" tag which contains some (but not really +all) of its categories. That could be done with one small +change: +.PP +.Vb 4 +\& # 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/; +\& } +.Ve +.PP +Note that the tag names in \f(CW%EXPORT_TAGS\fR don't have the leading ':'. +.ie n .SS """AUTOLOAD""ed Constants" +.el .SS "\f(CWAUTOLOAD\fPed Constants" +.IX Subsection "AUTOLOADed Constants" +Many modules make use of \f(CW\*(C`AUTOLOAD\*(C'\fRing for constant subroutines to +avoid having to compile and waste memory on rarely used values (see +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. +.PP +Even if a prototype is available at compile time, the body of the +subroutine is not (it hasn't been \f(CW\*(C`AUTOLOAD\*(C'\fRed yet). perl needs to +examine both the \f(CW\*(C`()\*(C'\fR 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. +.PP +A workaround for this is to call the constants once in a \f(CW\*(C`BEGIN\*(C'\fR block: +.PP +.Vb 1 +\& 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. +.Ve +.PP +This forces the \f(CW\*(C`AUTOLOAD\*(C'\fR for \f(CW\*(C`SO_LINGER\*(C'\fR to take place before +SO_LINGER is encountered later in \f(CW\*(C`My\*(C'\fR package. +.PP +If you are writing a package that \f(CW\*(C`AUTOLOAD\*(C'\fRs, consider forcing +an \f(CW\*(C`AUTOLOAD\*(C'\fR for any constants explicitly imported by other packages +or which are usually used when your package is \f(CW\*(C`use\*(C'\fRd. +.SH "Good Practices" +.IX Header "Good Practices" +.ie n .SS "Declaring @EXPORT_OK and Friends" +.el .SS "Declaring \f(CW@EXPORT_OK\fP and Friends" +.IX Subsection "Declaring @EXPORT_OK and Friends" +When using \f(CW\*(C`Exporter\*(C'\fR with the standard \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR +pragmas, the \f(CW\*(C`our\*(C'\fR keyword is needed to declare the package +variables \f(CW@EXPORT_OK\fR, \f(CW@EXPORT\fR, \f(CW@ISA\fR, etc. +.PP +.Vb 2 +\& our @ISA = qw(Exporter); +\& our @EXPORT_OK = qw(munge frobnicate); +.Ve +.PP +If backward compatibility for Perls \fBunder\fR 5.6 is important, +one must write instead a \f(CW\*(C`use vars\*(C'\fR statement. +.PP +.Vb 3 +\& use vars qw(@ISA @EXPORT_OK); +\& @ISA = qw(Exporter); +\& @EXPORT_OK = qw(munge frobnicate); +.Ve +.SS "Playing Safe" +.IX Subsection "Playing Safe" +There are some caveats with the use of runtime statements +like \f(CW\*(C`require Exporter\*(C'\fR and the assignment to package +variables, which can be 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. +.PP +The ideal way to never have to think about that is to use +\&\f(CW\*(C`BEGIN\*(C'\fR blocks and the simple import method. So the first part +of the "SYNOPSIS" code could be rewritten as: +.PP +.Vb 1 +\& package YourModule; +\& +\& use strict; +\& use warnings; +\& +\& use Exporter \*(Aqimport\*(Aq; +\& BEGIN { +\& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request +\& } +.Ve +.PP +Or if you need to inherit from Exporter: +.PP +.Vb 1 +\& package YourModule; +\& +\& use strict; +\& use warnings; +\& +\& BEGIN { +\& require Exporter; +\& our @ISA = qw(Exporter); # inherit all of Exporter\*(Aqs methods +\& our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request +\& } +.Ve +.PP +The \f(CW\*(C`BEGIN\*(C'\fR will assure that the loading of \fIExporter.pm\fR +and the assignments to \f(CW@ISA\fR and \f(CW@EXPORT_OK\fR happen +immediately like \f(CW\*(C`use\*(C'\fR, leaving no room for something to get awry +or just plain wrong. +.PP +With respect to loading \f(CW\*(C`Exporter\*(C'\fR and inheriting, there +are alternatives with the use of modules like \f(CW\*(C`base\*(C'\fR and \f(CW\*(C`parent\*(C'\fR. +.PP +.Vb 3 +\& use base qw(Exporter); +\& # or +\& use parent qw(Exporter); +.Ve +.PP +Any of these statements are nice replacements for +\&\f(CW\*(C`BEGIN { require Exporter; our @ISA = qw(Exporter); }\*(C'\fR +with the same compile-time effect. The basic difference +is that \f(CW\*(C`base\*(C'\fR code interacts with declared \f(CW\*(C`fields\*(C'\fR +while \f(CW\*(C`parent\*(C'\fR is a streamlined version of the older +\&\f(CW\*(C`base\*(C'\fR code to just establish the IS-A relationship. +.PP +For more details, see the documentation and code of +base and parent. +.PP +Another thorough remedy to that runtime +vs. compile-time trap is to use Exporter::Easy, +which is a wrapper of Exporter that allows all +boilerplate code at a single gulp in the +use statement. +.PP +.Vb 5 +\& use Exporter::Easy ( +\& OK => [ qw(munge frobnicate) ], +\& ); +\& # @ISA setup is automatic +\& # all assignments happen at compile time +.Ve +.SS "What Not to Export" +.IX Subsection "What Not to Export" +You have been warned already in "Selecting What to Export" +to not export: +.IP \(bu 4 +method names (because you don't need to +and that's likely to not do what you want), +.IP \(bu 4 +anything by default (because you don't want to surprise your users... +badly) +.IP \(bu 4 +anything you don't need to (because less is more) +.PP +There's one more item to add to this list. Do \fBnot\fR +export variable names. Just because \f(CW\*(C`Exporter\*(C'\fR lets you +do that, it does not mean you should. +.PP +.Vb 1 +\& @EXPORT_OK = qw($svar @avar %hvar); # DON\*(AqT! +.Ve +.PP +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. +.PP +To provide the capability to set/get class-wide +settings, it is best instead to provide accessors +as subroutines or class methods instead. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\f(CW\*(C`Exporter\*(C'\fR 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. Pick the one +that fits your needs. The following is +a sample list of such modules. +.PP +.Vb 6 +\& Exporter::Easy +\& Exporter::Lite +\& Exporter::Renaming +\& Exporter::Tidy +\& Sub::Exporter / Sub::Installer +\& Perl6::Export / Perl6::Export::Attrs +.Ve +.SH LICENSE +.IX Header "LICENSE" +This library is free software. You can redistribute it +and/or modify it under the same terms as Perl itself. |