Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.