diff options
Diffstat (limited to 'upstream/debian-unstable/man1/perlmod.1')
| -rw-r--r-- | upstream/debian-unstable/man1/perlmod.1 | 740 |
1 files changed, 740 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/perlmod.1 b/upstream/debian-unstable/man1/perlmod.1 new file mode 100644 index 00000000..4c3f1c85 --- /dev/null +++ b/upstream/debian-unstable/man1/perlmod.1 @@ -0,0 +1,740 @@ +.\" -*- 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 "PERLMOD 1" +.TH PERLMOD 1 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 +perlmod \- Perl modules (packages and symbol tables) +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SS "Is this the document you were after?" +.IX Subsection "Is this the document you were after?" +There are other documents which might contain the information that you're +looking for: +.IP "This doc" 2 +.IX Item "This doc" +Perl's packages, namespaces, and some info on classes. +.IP perlnewmod 2 +.IX Item "perlnewmod" +Tutorial on making a new module. +.IP perlmodstyle 2 +.IX Item "perlmodstyle" +Best practices for making a new module. +.SS Packages +.IX Xref "package namespace variable, global global variable global" +.IX Subsection "Packages" +Unlike Perl 4, in which all the variables were dynamic and shared one +global name space, causing maintainability problems, Perl 5 provides two +mechanisms for protecting code from having its variables stomped on by +other code: lexically scoped variables created with \f(CW\*(C`my\*(C'\fR or \f(CW\*(C`state\*(C'\fR and +namespaced global variables, which are exposed via the \f(CW\*(C`vars\*(C'\fR pragma, +or the \f(CW\*(C`our\*(C'\fR keyword. Any global variable is considered to +be part of a namespace and can be accessed via a "fully qualified form". +Conversely, any lexically scoped variable is considered to be part of +that lexical-scope, and does not have a "fully qualified form". +.PP +In perl namespaces are called "packages" and +the \f(CW\*(C`package\*(C'\fR declaration tells the compiler which +namespace to prefix to \f(CW\*(C`our\*(C'\fR variables and unqualified dynamic names. +This both protects +against accidental stomping and provides an interface for deliberately +clobbering global dynamic variables declared and used in other scopes or +packages, when that is what you want to do. +.PP +The scope of the \f(CW\*(C`package\*(C'\fR declaration is from the +declaration itself through the end of the enclosing block, \f(CW\*(C`eval\*(C'\fR, +or file, whichever comes first (the same scope as the \fBmy()\fR, \fBour()\fR, \fBstate()\fR, and +\&\fBlocal()\fR operators, and also the effect +of the experimental "reference aliasing," which may change), or until +the next \f(CW\*(C`package\*(C'\fR declaration. Unqualified dynamic identifiers will be in +this namespace, except for those few identifiers that, if unqualified, +default to the main package instead of the current one as described +below. A \f(CW\*(C`package\*(C'\fR statement affects only dynamic global +symbols, including subroutine names, and variables you've used \fBlocal()\fR +on, but \fInot\fR lexical variables created with \fBmy()\fR, \fBour()\fR or \fBstate()\fR. +.PP +Typically, a \f(CW\*(C`package\*(C'\fR statement is the first declaration in a file +included in a program by one of the \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR operators. You can +switch into a package in more than one place: \f(CW\*(C`package\*(C'\fR has no +effect beyond specifying which symbol table the compiler will use for +dynamic symbols for the rest of that block or until the next \f(CW\*(C`package\*(C'\fR statement. +You can refer to variables and filehandles in other packages +by prefixing the identifier with the package name and a double +colon: \f(CW$Package::Variable\fR. If the package name is null, the +\&\f(CW\*(C`main\*(C'\fR package is assumed. That is, \f(CW$::sail\fR is equivalent to +\&\f(CW$main::sail\fR. +.PP +The old package delimiter was a single quote, but double colon is now the +preferred delimiter, in part because it's more readable to humans, and +in part because it's more readable to \fBemacs\fR macros. It also makes C++ +programmers feel like they know what's going on\-\-as opposed to using the +single quote as separator, which was there to make Ada programmers feel +like they knew what was going on. Because the old-fashioned syntax is still +supported for backwards compatibility, if you try to use a string like +\&\f(CW"This is $owner\*(Aqs house"\fR, you'll be accessing \f(CW$owner::s\fR; that is, +the \f(CW$s\fR variable in package \f(CW\*(C`owner\*(C'\fR, which is probably not what you meant. +Use braces to disambiguate, as in \f(CW"This is ${owner}\*(Aqs house"\fR. +.IX Xref ":: '" +.PP +Using \f(CW\*(C`\*(Aq\*(C'\fR as a package separator is deprecated and will be removed in +Perl 5.40. +.PP +Packages may themselves contain package separators, as in +\&\f(CW$OUTER::INNER::var\fR. This implies nothing about the order of +name lookups, however. There are no relative packages: all symbols +are either local to the current package, or must be fully qualified +from the outer package name down. For instance, there is nowhere +within package \f(CW\*(C`OUTER\*(C'\fR that \f(CW$INNER::var\fR refers to +\&\f(CW$OUTER::INNER::var\fR. \f(CW\*(C`INNER\*(C'\fR refers to a totally +separate global package. The custom of treating package names as a +hierarchy is very strong, but the language in no way enforces it. +.PP +Only identifiers starting with letters (or underscore) are stored +in a package's symbol table. All other symbols are kept in package +\&\f(CW\*(C`main\*(C'\fR, including all punctuation variables, like \f(CW$_\fR. In addition, +when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV, +ARGVOUT, ENV, INC, and SIG are forced to be in package \f(CW\*(C`main\*(C'\fR, +even when used for other purposes than their built-in ones. If you +have a package called \f(CW\*(C`m\*(C'\fR, \f(CW\*(C`s\*(C'\fR, or \f(CW\*(C`y\*(C'\fR, then you can't use the +qualified form of an identifier because it would be instead interpreted +as a pattern match, a substitution, or a transliteration. +.IX Xref "variable, punctuation" +.PP +Variables beginning with underscore used to be forced into package +main, but we decided it was more useful for package writers to be able +to use leading underscore to indicate private variables and method names. +However, variables and functions named with a single \f(CW\*(C`_\*(C'\fR, such as +\&\f(CW$_\fR and \f(CW\*(C`sub _\*(C'\fR, are still forced into the package \f(CW\*(C`main\*(C'\fR. See also +"The Syntax of Variable Names" in perlvar. +.PP +\&\f(CW\*(C`eval\*(C'\fRed strings are compiled in the package in which the \fBeval()\fR was +compiled. (Assignments to \f(CW\*(C`$SIG{}\*(C'\fR, however, assume the signal +handler specified is in the \f(CW\*(C`main\*(C'\fR package. Qualify the signal handler +name if you wish to have a signal handler in a package.) For an +example, examine \fIperldb.pl\fR in the Perl library. It initially switches +to the \f(CW\*(C`DB\*(C'\fR package so that the debugger doesn't interfere with variables +in the program you are trying to debug. At various points, however, it +temporarily switches back to the \f(CW\*(C`main\*(C'\fR package to evaluate various +expressions in the context of the \f(CW\*(C`main\*(C'\fR package (or wherever you came +from). See perldebug. +.PP +The special symbol \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR contains the current package, but cannot +(easily) be used to construct variable names. After \f(CWmy($foo)\fR has hidden +package variable \f(CW$foo\fR, it can still be accessed, without knowing what +package you are in, as \f(CW\*(C`${_\|_PACKAGE_\|_.\*(Aq::foo\*(Aq}\*(C'\fR. +.PP +See perlsub for other scoping issues related to \fBmy()\fR and \fBlocal()\fR, +and perlref regarding closures. +.SS "Symbol Tables" +.IX Xref "symbol table stash %:: %main:: typeglob glob alias" +.IX Subsection "Symbol Tables" +The symbol table for a package happens to be stored in the hash of that +name with two colons appended. The main symbol table's name is thus +\&\f(CW%main::\fR, or \f(CW%::\fR for short. Likewise the symbol table for the nested +package mentioned earlier is named \f(CW%OUTER::INNER::\fR. +.PP +The value in each entry of the hash is what you are referring to when you +use the \f(CW*name\fR typeglob notation. +.PP +.Vb 1 +\& local *main::foo = *main::bar; +.Ve +.PP +You can use this to print out all the variables in a package, for +instance. The standard but antiquated \fIdumpvar.pl\fR library and +the CPAN module Devel::Symdump make use of this. +.PP +The results of creating new symbol table entries directly or modifying any +entries that are not already typeglobs are undefined and subject to change +between releases of perl. +.PP +Assignment to a typeglob performs an aliasing operation, i.e., +.PP +.Vb 1 +\& *dick = *richard; +.Ve +.PP +causes variables, subroutines, formats, and file and directory handles +accessible via the identifier \f(CW\*(C`richard\*(C'\fR also to be accessible via the +identifier \f(CW\*(C`dick\*(C'\fR. If you want to alias only a particular variable or +subroutine, assign a reference instead: +.PP +.Vb 1 +\& *dick = \e$richard; +.Ve +.PP +Which makes \f(CW$richard\fR and \f(CW$dick\fR the same variable, but leaves +\&\f(CW@richard\fR and \f(CW@dick\fR as separate arrays. Tricky, eh? +.PP +There is one subtle difference between the following statements: +.PP +.Vb 2 +\& *foo = *bar; +\& *foo = \e$bar; +.Ve +.PP +\&\f(CW\*(C`*foo = *bar\*(C'\fR makes the typeglobs themselves synonymous while +\&\f(CW\*(C`*foo = \e$bar\*(C'\fR makes the SCALAR portions of two distinct typeglobs +refer to the same scalar value. This means that the following code: +.PP +.Vb 2 +\& $bar = 1; +\& *foo = \e$bar; # Make $foo an alias for $bar +\& +\& { +\& local $bar = 2; # Restrict changes to block +\& print $foo; # Prints \*(Aq1\*(Aq! +\& } +.Ve +.PP +Would print '1', because \f(CW$foo\fR holds a reference to the \fIoriginal\fR +\&\f(CW$bar\fR. The one that was stuffed away by \f(CWlocal()\fR and which will be +restored when the block ends. Because variables are accessed through the +typeglob, you can use \f(CW\*(C`*foo = *bar\*(C'\fR to create an alias which can be +localized. (But be aware that this means you can't have a separate +\&\f(CW@foo\fR and \f(CW@bar\fR, etc.) +.PP +What makes all of this important is that the Exporter module uses glob +aliasing as the import/export mechanism. Whether or not you can properly +localize a variable that has been exported from a module depends on how +it was exported: +.PP +.Vb 2 +\& @EXPORT = qw($FOO); # Usual form, can\*(Aqt be localized +\& @EXPORT = qw(*FOO); # Can be localized +.Ve +.PP +You can work around the first case by using the fully qualified name +(\f(CW$Package::FOO\fR) where you need a local value, or by overriding it +by saying \f(CW\*(C`*FOO = *Package::FOO\*(C'\fR in your script. +.PP +The \f(CW\*(C`*x = \e$y\*(C'\fR mechanism may be used to pass and return cheap references +into or from subroutines if you don't want to copy the whole +thing. It only works when assigning to dynamic variables, not +lexicals. +.PP +.Vb 9 +\& %some_hash = (); # can\*(Aqt be my() +\& *some_hash = fn( \e%another_hash ); +\& sub fn { +\& local *hashsym = shift; +\& # now use %hashsym normally, and you +\& # will affect the caller\*(Aqs %another_hash +\& my %nhash = (); # do what you want +\& return \e%nhash; +\& } +.Ve +.PP +On return, the reference will overwrite the hash slot in the +symbol table specified by the *some_hash typeglob. This +is a somewhat tricky way of passing around references cheaply +when you don't want to have to remember to dereference variables +explicitly. +.PP +Another use of symbol tables is for making "constant" scalars. +.IX Xref "constant scalar, constant" +.PP +.Vb 1 +\& *PI = \e3.14159265358979; +.Ve +.PP +Now you cannot alter \f(CW$PI\fR, which is probably a good thing all in all. +This isn't the same as a constant subroutine, which is subject to +optimization at compile-time. A constant subroutine is one prototyped +to take no arguments and to return a constant expression. See +perlsub for details on these. The \f(CW\*(C`use constant\*(C'\fR pragma is a +convenient shorthand for these. +.PP +You can say \f(CW*foo{PACKAGE}\fR and \f(CW*foo{NAME}\fR to find out what name and +package the *foo symbol table entry comes from. This may be useful +in a subroutine that gets passed typeglobs as arguments: +.PP +.Vb 7 +\& sub identify_typeglob { +\& my $glob = shift; +\& print \*(AqYou gave me \*(Aq, *{$glob}{PACKAGE}, +\& \*(Aq::\*(Aq, *{$glob}{NAME}, "\en"; +\& } +\& identify_typeglob *foo; +\& identify_typeglob *bar::baz; +.Ve +.PP +This prints +.PP +.Vb 2 +\& You gave me main::foo +\& You gave me bar::baz +.Ve +.PP +The \f(CW*foo{THING}\fR notation can also be used to obtain references to the +individual elements of *foo. See perlref. +.PP +Subroutine definitions (and declarations, for that matter) need +not necessarily be situated in the package whose symbol table they +occupy. You can define a subroutine outside its package by +explicitly qualifying the name of the subroutine: +.PP +.Vb 2 +\& package main; +\& sub Some_package::foo { ... } # &foo defined in Some_package +.Ve +.PP +This is just a shorthand for a typeglob assignment at compile time: +.PP +.Vb 1 +\& BEGIN { *Some_package::foo = sub { ... } } +.Ve +.PP +and is \fInot\fR the same as writing: +.PP +.Vb 4 +\& { +\& package Some_package; +\& sub foo { ... } +\& } +.Ve +.PP +In the first two versions, the body of the subroutine is +lexically in the main package, \fInot\fR in Some_package. So +something like this: +.PP +.Vb 1 +\& package main; +\& +\& $Some_package::name = "fred"; +\& $main::name = "barney"; +\& +\& sub Some_package::foo { +\& print "in ", _\|_PACKAGE_\|_, ": \e$name is \*(Aq$name\*(Aq\en"; +\& } +\& +\& Some_package::foo(); +.Ve +.PP +prints: +.PP +.Vb 1 +\& in main: $name is \*(Aqbarney\*(Aq +.Ve +.PP +rather than: +.PP +.Vb 1 +\& in Some_package: $name is \*(Aqfred\*(Aq +.Ve +.PP +This also has implications for the use of the SUPER:: qualifier +(see perlobj). +.SS "BEGIN, UNITCHECK, CHECK, INIT and END" +.IX Xref "BEGIN UNITCHECK CHECK INIT END" +.IX Subsection "BEGIN, UNITCHECK, CHECK, INIT and END" +Five specially named code blocks are executed at the beginning and at +the end of a running Perl program. These are the \f(CW\*(C`BEGIN\*(C'\fR, +\&\f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, and \f(CW\*(C`END\*(C'\fR blocks. +.PP +These code blocks can be prefixed with \f(CW\*(C`sub\*(C'\fR to give the appearance of a +subroutine (although this is not considered good style). One should note +that these code blocks don't really exist as named subroutines (despite +their appearance). The thing that gives this away is the fact that you can +have \fBmore than one\fR of these code blocks in a program, and they will get +\&\fBall\fR executed at the appropriate moment. So you can't execute any of +these code blocks by name. +.PP +A \f(CW\*(C`BEGIN\*(C'\fR code block is executed as soon as possible, that is, the moment +it is completely defined, even before the rest of the containing file (or +string) is parsed. You may have multiple \f(CW\*(C`BEGIN\*(C'\fR blocks within a file (or +eval'ed string); they will execute in order of definition. Because a \f(CW\*(C`BEGIN\*(C'\fR +code block executes immediately, it can pull in definitions of subroutines +and such from other files in time to be visible to the rest of the compile +and run time. Once a \f(CW\*(C`BEGIN\*(C'\fR has run, it is immediately undefined and any +code it used is returned to Perl's memory pool. +.PP +An \f(CW\*(C`END\*(C'\fR code block is executed as late as possible, that is, after +perl has finished running the program and just before the interpreter +is being exited, even if it is exiting as a result of a \fBdie()\fR function. +(But not if it's morphing into another program via \f(CW\*(C`exec\*(C'\fR, or +being blown out of the water by a signal\-\-you have to trap that yourself +(if you can).) You may have multiple \f(CW\*(C`END\*(C'\fR blocks within a file\-\-they +will execute in reverse order of definition; that is: last in, first +out (LIFO). \f(CW\*(C`END\*(C'\fR blocks are not executed when you run perl with the +\&\f(CW\*(C`\-c\*(C'\fR switch, or if compilation fails. +.PP +Note that \f(CW\*(C`END\*(C'\fR code blocks are \fBnot\fR executed at the end of a string +\&\f(CWeval()\fR: if any \f(CW\*(C`END\*(C'\fR code blocks are created in a string \f(CWeval()\fR, +they will be executed just as any other \f(CW\*(C`END\*(C'\fR code block of that package +in LIFO order just before the interpreter is being exited. +.PP +Inside an \f(CW\*(C`END\*(C'\fR code block, \f(CW$?\fR contains the value that the program is +going to pass to \f(CWexit()\fR. You can modify \f(CW$?\fR to change the exit +value of the program. Beware of changing \f(CW$?\fR by accident (e.g. by +running something via \f(CW\*(C`system\*(C'\fR). +.IX Xref "$?" +.PP +Inside of a \f(CW\*(C`END\*(C'\fR block, the value of \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR will be +\&\f(CW"END"\fR. +.PP +Similar to an \f(CW\*(C`END\*(C'\fR block are \f(CW\*(C`defer\*(C'\fR blocks, though they operate on the +lifetime of individual block scopes, rather than the program as a whole. They +are documented in "defer" in perlsyn. +.PP +\&\f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR and \f(CW\*(C`INIT\*(C'\fR code blocks are useful to catch the +transition between the compilation phase and the execution phase of +the main program. +.PP +\&\f(CW\*(C`UNITCHECK\*(C'\fR blocks are run just after the unit which defined them has +been compiled. The main program file and each module it loads are +compilation units, as are string \f(CW\*(C`eval\*(C'\fRs, run-time code compiled using the +\&\f(CW\*(C`(?{ })\*(C'\fR construct in a regex, calls to \f(CW\*(C`do FILE\*(C'\fR, \f(CW\*(C`require FILE\*(C'\fR, +and code after the \f(CW\*(C`\-e\*(C'\fR switch on the command line. +.PP +\&\f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`UNITCHECK\*(C'\fR blocks are not directly related to the phase of +the interpreter. They can be created and executed during any phase. +.PP +\&\f(CW\*(C`CHECK\*(C'\fR code blocks are run just after the \fBinitial\fR Perl compile phase ends +and before the run time begins, in LIFO order. \f(CW\*(C`CHECK\*(C'\fR code blocks are used +in the Perl compiler suite to save the compiled state of the program. +.PP +Inside of a \f(CW\*(C`CHECK\*(C'\fR block, the value of \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR will be +\&\f(CW"CHECK"\fR. +.PP +\&\f(CW\*(C`INIT\*(C'\fR blocks are run just before the Perl runtime begins execution, in +"first in, first out" (FIFO) order. +.PP +Inside of an \f(CW\*(C`INIT\*(C'\fR block, the value of \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR will be \f(CW"INIT"\fR. +.PP +The \f(CW\*(C`CHECK\*(C'\fR and \f(CW\*(C`INIT\*(C'\fR blocks in code compiled by \f(CW\*(C`require\*(C'\fR, string \f(CW\*(C`do\*(C'\fR, +or string \f(CW\*(C`eval\*(C'\fR will not be executed if they occur after the end of the +main compilation phase; that can be a problem in mod_perl and other persistent +environments which use those functions to load code at runtime. +.PP +When you use the \fB\-n\fR and \fB\-p\fR switches to Perl, \f(CW\*(C`BEGIN\*(C'\fR and +\&\f(CW\*(C`END\*(C'\fR work just as they do in \fBawk\fR, as a degenerate case. +Both \f(CW\*(C`BEGIN\*(C'\fR and \f(CW\*(C`CHECK\*(C'\fR blocks are run when you use the \fB\-c\fR +switch for a compile-only syntax check, although your main code +is not. +.PP +The \fBbegincheck\fR program makes it all clear, eventually: +.PP +.Vb 1 +\& #!/usr/bin/perl +\& +\& # begincheck +\& +\& print "10. Ordinary code runs at runtime.\en"; +\& +\& END { print "16. So this is the end of the tale.\en" } +\& INIT { print " 7. INIT blocks run FIFO just before runtime.\en" } +\& UNITCHECK { +\& print " 4. And therefore before any CHECK blocks.\en" +\& } +\& CHECK { print " 6. So this is the sixth line.\en" } +\& +\& print "11. It runs in order, of course.\en"; +\& +\& BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\en" } +\& END { print "15. Read perlmod for the rest of the story.\en" } +\& CHECK { print " 5. CHECK blocks run LIFO after all compilation.\en" } +\& INIT { print " 8. Run this again, using Perl\*(Aqs \-c switch.\en" } +\& +\& print "12. This is anti\-obfuscated code.\en"; +\& +\& END { print "14. END blocks run LIFO at quitting time.\en" } +\& BEGIN { print " 2. So this line comes out second.\en" } +\& UNITCHECK { +\& print " 3. UNITCHECK blocks run LIFO after each file is compiled.\en" +\& } +\& INIT { print " 9. You\*(Aqll see the difference right away.\en" } +\& +\& print "13. It only _looks_ like it should be confusing.\en"; +\& +\& _\|_END_\|_ +.Ve +.SS "Perl Classes" +.IX Xref "class @ISA" +.IX Subsection "Perl Classes" +There is no special class syntax in Perl, but a package may act +as a class if it provides subroutines to act as methods. Such a +package may also derive some of its methods from another class (package) +by listing the other package name(s) in its global \f(CW@ISA\fR array (which +must be a package global, not a lexical). +.PP +For more on this, see perlootut and perlobj. +.SS "Perl Modules" +.IX Xref "module" +.IX Subsection "Perl Modules" +A module is just a set of related functions in a library file, i.e., +a Perl package with the same name as the file. It is specifically +designed to be reusable by other modules or programs. It may do this +by providing a mechanism for exporting some of its symbols into the +symbol table of any package using it, or it may function as a class +definition and make its semantics available implicitly through +method calls on the class and its objects, without explicitly +exporting anything. Or it can do a little of both. +.PP +For example, to start a traditional, non-OO module called Some::Module, +create a file called \fISome/Module.pm\fR and start with this template: +.PP +.Vb 1 +\& package Some::Module; # assumes Some/Module.pm +\& +\& use v5.36; +\& +\& # Get the import method from Exporter to export functions and +\& # variables +\& use Exporter 5.57 \*(Aqimport\*(Aq; +\& +\& # set the version for version checking +\& our $VERSION = \*(Aq1.00\*(Aq; +\& +\& # Functions and variables which are exported by default +\& our @EXPORT = qw(func1 func2); +\& +\& # Functions and variables which can be optionally exported +\& our @EXPORT_OK = qw($Var1 %Hashit func3); +\& +\& # exported package globals go here +\& our $Var1 = \*(Aq\*(Aq; +\& our %Hashit = (); +\& +\& # non\-exported package globals go here +\& # (they are still accessible as $Some::Module::stuff) +\& our @more = (); +\& our $stuff = \*(Aq\*(Aq; +\& +\& # file\-private lexicals go here, before any functions which use them +\& my $priv_var = \*(Aq\*(Aq; +\& my %secret_hash = (); +\& +\& # here\*(Aqs a file\-private function as a closure, +\& # callable as $priv_func\->(); +\& my $priv_func = sub { +\& ... +\& }; +\& +\& # make all your functions, whether exported or not; +\& # remember to put something interesting in the {} stubs +\& sub func1 { ... } +\& sub func2 { ... } +\& +\& # this one isn\*(Aqt always exported, but could be called directly +\& # as Some::Module::func3() +\& sub func3 { ... } +\& +\& END { ... } # module clean\-up code here (global destructor) +\& +\& 1; # don\*(Aqt forget to return a true value from the file +.Ve +.PP +Then go on to declare and use your variables in functions without +any qualifications. See Exporter and the perlmodlib for +details on mechanics and style issues in module creation. +.PP +Perl modules are included into your program by saying +.PP +.Vb 1 +\& use Module; +.Ve +.PP +or +.PP +.Vb 1 +\& use Module LIST; +.Ve +.PP +This is exactly equivalent to +.PP +.Vb 1 +\& BEGIN { require \*(AqModule.pm\*(Aq; \*(AqModule\*(Aq\->import; } +.Ve +.PP +or +.PP +.Vb 1 +\& BEGIN { require \*(AqModule.pm\*(Aq; \*(AqModule\*(Aq\->import( LIST ); } +.Ve +.PP +As a special case +.PP +.Vb 1 +\& use Module (); +.Ve +.PP +is exactly equivalent to +.PP +.Vb 1 +\& BEGIN { require \*(AqModule.pm\*(Aq; } +.Ve +.PP +All Perl module files have the extension \fI.pm\fR. The \f(CW\*(C`use\*(C'\fR operator +assumes this so you don't have to spell out "\fIModule.pm\fR" in quotes. +This also helps to differentiate new modules from old \fI.pl\fR and +\&\fI.ph\fR files. Module names are also capitalized unless they're +functioning as pragmas; pragmas are in effect compiler directives, +and are sometimes called "pragmatic modules" (or even "pragmata" +if you're a classicist). +.PP +The two statements: +.PP +.Vb 2 +\& require SomeModule; +\& require "SomeModule.pm"; +.Ve +.PP +differ from each other in two ways. In the first case, any double +colons in the module name, such as \f(CW\*(C`Some::Module\*(C'\fR, are translated +into your system's directory separator, usually "/". The second +case does not, and would have to be specified literally. The other +difference is that seeing the first \f(CW\*(C`require\*(C'\fR clues in the compiler +that uses of indirect object notation involving "SomeModule", as +in \f(CW\*(C`$ob = purge SomeModule\*(C'\fR, are method calls, not function calls. +(Yes, this really can make a difference.) +.PP +Because the \f(CW\*(C`use\*(C'\fR statement implies a \f(CW\*(C`BEGIN\*(C'\fR block, the importing +of semantics happens as soon as the \f(CW\*(C`use\*(C'\fR statement is compiled, +before the rest of the file is compiled. This is how it is able +to function as a pragma mechanism, and also how modules are able to +declare subroutines that are then visible as list or unary operators for +the rest of the current file. This will not work if you use \f(CW\*(C`require\*(C'\fR +instead of \f(CW\*(C`use\*(C'\fR. With \f(CW\*(C`require\*(C'\fR you can get into this problem: +.PP +.Vb 2 +\& require Cwd; # make Cwd:: accessible +\& $here = Cwd::getcwd(); +\& +\& use Cwd; # import names from Cwd:: +\& $here = getcwd(); +\& +\& require Cwd; # make Cwd:: accessible +\& $here = getcwd(); # oops! no main::getcwd() +.Ve +.PP +In general, \f(CW\*(C`use Module ()\*(C'\fR is recommended over \f(CW\*(C`require Module\*(C'\fR, +because it determines module availability at compile time, not in the +middle of your program's execution. An exception would be if two modules +each tried to \f(CW\*(C`use\*(C'\fR each other, and each also called a function from +that other module. In that case, it's easy to use \f(CW\*(C`require\*(C'\fR instead. +.PP +Perl packages may be nested inside other package names, so we can have +package names containing \f(CW\*(C`::\*(C'\fR. But if we used that package name +directly as a filename it would make for unwieldy or impossible +filenames on some systems. Therefore, if a module's name is, say, +\&\f(CW\*(C`Text::Soundex\*(C'\fR, then its definition is actually found in the library +file \fIText/Soundex.pm\fR. +.PP +Perl modules always have a \fI.pm\fR file, but there may also be +dynamically linked executables (often ending in \fI.so\fR) or autoloaded +subroutine definitions (often ending in \fI.al\fR) associated with the +module. If so, these will be entirely transparent to the user of +the module. It is the responsibility of the \fI.pm\fR file to load +(or arrange to autoload) any additional functionality. For example, +although the POSIX module happens to do both dynamic loading and +autoloading, the user can say just \f(CW\*(C`use POSIX\*(C'\fR to get it all. +.SS "Making your module threadsafe" +.IX Xref "threadsafe thread safe module, threadsafe module, thread safe CLONE CLONE_SKIP thread threads ithread" +.IX Subsection "Making your module threadsafe" +Perl supports a type of threads called interpreter threads (ithreads). +These threads can be used explicitly and implicitly. +.PP +Ithreads work by cloning the data tree so that no data is shared +between different threads. These threads can be used by using the \f(CW\*(C`threads\*(C'\fR +module or by doing \fBfork()\fR on win32 (fake \fBfork()\fR support). When a +thread is cloned all Perl data is cloned, however non-Perl data cannot +be cloned automatically. Perl after 5.8.0 has support for the \f(CW\*(C`CLONE\*(C'\fR +special subroutine. In \f(CW\*(C`CLONE\*(C'\fR you can do whatever +you need to do, +like for example handle the cloning of non-Perl data, if necessary. +\&\f(CW\*(C`CLONE\*(C'\fR will be called once as a class method for every package that has it +defined (or inherits it). It will be called in the context of the new thread, +so all modifications are made in the new area. Currently CLONE is called with +no parameters other than the invocant package name, but code should not assume +that this will remain unchanged, as it is likely that in future extra parameters +will be passed in to give more information about the state of cloning. +.PP +If you want to CLONE all objects you will need to keep track of them per +package. This is simply done using a hash and \fBScalar::Util::weaken()\fR. +.PP +Perl after 5.8.7 has support for the \f(CW\*(C`CLONE_SKIP\*(C'\fR special subroutine. +Like \f(CW\*(C`CLONE\*(C'\fR, \f(CW\*(C`CLONE_SKIP\*(C'\fR is called once per package; however, it is +called just before cloning starts, and in the context of the parent +thread. If it returns a true value, then no objects of that class will +be cloned; or rather, they will be copied as unblessed, undef values. +For example: if in the parent there are two references to a single blessed +hash, then in the child there will be two references to a single undefined +scalar value instead. +This provides a simple mechanism for making a module threadsafe; just add +\&\f(CW\*(C`sub CLONE_SKIP { 1 }\*(C'\fR at the top of the class, and \f(CWDESTROY()\fR will +now only be called once per object. Of course, if the child thread needs +to make use of the objects, then a more sophisticated approach is +needed. +.PP +Like \f(CW\*(C`CLONE\*(C'\fR, \f(CW\*(C`CLONE_SKIP\*(C'\fR is currently called with no parameters other +than the invocant package name, although that may change. Similarly, to +allow for future expansion, the return value should be a single \f(CW0\fR or +\&\f(CW1\fR value. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See perlmodlib for general style issues related to building Perl +modules and classes, as well as descriptions of the standard library +and CPAN, Exporter for how Perl's standard import/export mechanism +works, perlootut and perlobj for in-depth information on +creating classes, perlobj for a hard-core reference document on +objects, perlsub for an explanation of functions and scoping, +and perlxstut and perlguts for more information on writing +extension modules. |