Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 312 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/constant.3perl b/upstream/archlinux/man3/constant.3perl
new file mode 100644
index 00000000..c26a462f
--- /dev/null
+++ b/upstream/archlinux/man3/constant.3perl
@@ -0,0 +1,312 @@
+.\" -*- 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 "constant 3perl"
+.TH constant 3perl 2024-02-11 "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
+constant \- Perl pragma to declare constants
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    use constant PI    => 4 * atan2(1, 1);
+\&    use constant DEBUG => 0;
+\&
+\&    print "Pi equals ", PI, "...\en" if DEBUG;
+\&
+\&    use constant {
+\&        SEC   => 0,
+\&        MIN   => 1,
+\&        HOUR  => 2,
+\&        MDAY  => 3,
+\&        MON   => 4,
+\&        YEAR  => 5,
+\&        WDAY  => 6,
+\&        YDAY  => 7,
+\&        ISDST => 8,
+\&    };
+\&
+\&    use constant WEEKDAYS => qw(
+\&        Sunday Monday Tuesday Wednesday Thursday Friday Saturday
+\&    );
+\&
+\&    print "Today is ", (WEEKDAYS)[ (localtime)[WDAY] ], ".\en";
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This pragma allows you to declare constants at compile-time.
+.PP
+When you declare a constant such as \f(CW\*(C`PI\*(C'\fR using the method shown
+above, each machine your script runs upon can have as many digits
+of accuracy as it can use.  Also, your program will be easier to
+read, more likely to be maintained (and maintained correctly), and
+far less likely to send a space probe to the wrong planet because
+nobody noticed the one equation in which you wrote \f(CW3.14195\fR.
+.PP
+When a constant is used in an expression, Perl replaces it with its
+value at compile time, and may then optimize the expression further.
+In particular, any code in an \f(CW\*(C`if (CONSTANT)\*(C'\fR block will be optimized
+away if the constant is false.
+.SH NOTES
+.IX Header "NOTES"
+As with all \f(CW\*(C`use\*(C'\fR directives, defining a constant happens at
+compile time.  Thus, it's probably not correct to put a constant
+declaration inside of a conditional statement (like \f(CW\*(C`if ($foo)
+{ use constant ... }\*(C'\fR).
+.PP
+Constants defined using this module cannot be interpolated into
+strings like variables.  However, concatenation works just fine:
+.PP
+.Vb 2
+\&    print "Pi equals PI...\en";        # WRONG: does not expand "PI"
+\&    print "Pi equals ".PI."...\en";    # right
+.Ve
+.PP
+Even though a reference may be declared as a constant, the reference may
+point to data which may be changed, as this code shows.
+.PP
+.Vb 4
+\&    use constant ARRAY => [ 1,2,3,4 ];
+\&    print ARRAY\->[1];
+\&    ARRAY\->[1] = " be changed";
+\&    print ARRAY\->[1];
+.Ve
+.PP
+Constants belong to the package they are defined in.  To refer to a
+constant defined in another package, specify the full package name, as
+in \f(CW\*(C`Some::Package::CONSTANT\*(C'\fR.  Constants may be exported by modules,
+and may also be called as either class or instance methods, that is,
+as \f(CW\*(C`Some::Package\->CONSTANT\*(C'\fR or as \f(CW\*(C`$obj\->CONSTANT\*(C'\fR where
+\&\f(CW$obj\fR is an instance of \f(CW\*(C`Some::Package\*(C'\fR.  Subclasses may define
+their own constants to override those in their base class.
+.PP
+As of version 1.32 of this module, constants can be defined in packages
+other than the caller, by including the package name in the name of the
+constant:
+.PP
+.Vb 2
+\&    use constant "OtherPackage::FWIBBLE" => 7865;
+\&    constant\->import("Other::FWOBBLE",$value); # dynamically at run time
+.Ve
+.PP
+The use of all caps for constant names is merely a convention,
+although it is recommended in order to make constants stand out
+and to help avoid collisions with other barewords, keywords, and
+subroutine names.  Constant names must begin with a letter or
+underscore.  Names beginning with a double underscore are reserved.  Some
+poor choices for names will generate warnings, if warnings are enabled at
+compile time.
+.SS "List constants"
+.IX Subsection "List constants"
+Constants may be lists of more (or less) than one value.  A constant
+with no values evaluates to \f(CW\*(C`undef\*(C'\fR in scalar context.  Note that
+constants with more than one value do \fInot\fR return their last value in
+scalar context as one might expect.  They currently return the number
+of values, but \fBthis may change in the future\fR.  Do not use constants
+with multiple values in scalar context.
+.PP
+\&\fBNOTE:\fR This implies that the expression defining the value of a
+constant is evaluated in list context.  This may produce surprises:
+.PP
+.Vb 2
+\&    use constant TIMESTAMP => localtime;                # WRONG!
+\&    use constant TIMESTAMP => scalar localtime;         # right
+.Ve
+.PP
+The first line above defines \f(CW\*(C`TIMESTAMP\*(C'\fR as a 9\-element list, as
+returned by \f(CWlocaltime()\fR in list context.  To set it to the string
+returned by \f(CWlocaltime()\fR in scalar context, an explicit \f(CW\*(C`scalar\*(C'\fR
+keyword is required.
+.PP
+List constants are lists, not arrays.  To index or slice them, they
+must be placed in parentheses.
+.PP
+.Vb 2
+\&    my @workdays = WEEKDAYS[1 .. 5];            # WRONG!
+\&    my @workdays = (WEEKDAYS)[1 .. 5];          # right
+.Ve
+.SS "Defining multiple constants at once"
+.IX Subsection "Defining multiple constants at once"
+Instead of writing multiple \f(CW\*(C`use constant\*(C'\fR statements, you may define
+multiple constants in a single statement by giving, instead of the
+constant name, a reference to a hash where the keys are the names of
+the constants to be defined.  Obviously, all constants defined using
+this method must have a single value.
+.PP
+.Vb 4
+\&    use constant {
+\&        FOO => "A single value",
+\&        BAR => "This", "won\*(Aqt", "work!",        # Error!
+\&    };
+.Ve
+.PP
+This is a fundamental limitation of the way hashes are constructed in
+Perl.  The error messages produced when this happens will often be
+quite cryptic \-\- in the worst case there may be none at all, and
+you'll only later find that something is broken.
+.PP
+When defining multiple constants, you cannot use the values of other
+constants defined in the same declaration.  This is because the
+calling package doesn't know about any constant within that group
+until \fIafter\fR the \f(CW\*(C`use\*(C'\fR statement is finished.
+.PP
+.Vb 4
+\&    use constant {
+\&        BITMASK => 0xAFBAEBA8,
+\&        NEGMASK => ~BITMASK,                    # Error!
+\&    };
+.Ve
+.SS "Magic constants"
+.IX Subsection "Magic constants"
+Magical values and references can be made into constants at compile
+time, allowing for way cool stuff like this.  (These error numbers
+aren't totally portable, alas.)
+.PP
+.Vb 3
+\&    use constant E2BIG => ($! = 7);
+\&    print   E2BIG, "\en";        # something like "Arg list too long"
+\&    print 0+E2BIG, "\en";        # "7"
+.Ve
+.PP
+You can't produce a tied constant by giving a tied scalar as the
+value.  References to tied variables, however, can be used as
+constants without any problems.
+.SH "TECHNICAL NOTES"
+.IX Header "TECHNICAL NOTES"
+In the current implementation, scalar constants are actually
+inlinable subroutines.  As of version 5.004 of Perl, the appropriate
+scalar constant is inserted directly in place of some subroutine
+calls, thereby saving the overhead of a subroutine call.  See
+"Constant Functions" in perlsub for details about how and when this
+happens.
+.PP
+In the rare case in which you need to discover at run time whether a
+particular constant has been declared via this module, you may use
+this function to examine the hash \f(CW%constant::declared\fR.  If the given
+constant name does not include a package name, the current package is
+used.
+.PP
+.Vb 8
+\&    sub declared ($) {
+\&        use constant 1.01;              # don\*(Aqt omit this!
+\&        my $name = shift;
+\&        $name =~ s/^::/main::/;
+\&        my $pkg = caller;
+\&        my $full_name = $name =~ /::/ ? $name : "${pkg}::$name";
+\&        $constant::declared{$full_name};
+\&    }
+.Ve
+.SH CAVEATS
+.IX Header "CAVEATS"
+List constants are not inlined unless you are using Perl v5.20 or higher.
+In v5.20 or higher, they are still not read-only, but that may change in
+future versions.
+.PP
+It is not possible to have a subroutine or a keyword with the same
+name as a constant in the same package.  This is probably a Good Thing.
+.PP
+A constant with a name in the list \f(CW\*(C`STDIN STDOUT STDERR ARGV ARGVOUT
+ENV INC SIG\*(C'\fR is not allowed anywhere but in package \f(CW\*(C`main::\*(C'\fR, for
+technical reasons.
+.PP
+Unlike constants in some languages, these cannot be overridden
+on the command line or via environment variables.
+.PP
+You can get into trouble if you use constants in a context which
+automatically quotes barewords (as is true for any subroutine call).
+For example, you can't say \f(CW$hash{CONSTANT}\fR because \f(CW\*(C`CONSTANT\*(C'\fR will
+be interpreted as a string.  Use \f(CW$hash{CONSTANT()}\fR or
+\&\f(CW$hash{+CONSTANT}\fR to prevent the bareword quoting mechanism from
+kicking in.  Similarly, since the \f(CW\*(C`=>\*(C'\fR operator quotes a bareword
+immediately to its left, you have to say \f(CW\*(C`CONSTANT() => \*(Aqvalue\*(Aq\*(C'\fR
+(or simply use a comma in place of the big arrow) instead of
+\&\f(CW\*(C`CONSTANT => \*(Aqvalue\*(Aq\*(C'\fR.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Readonly \- Facility for creating read-only scalars, arrays, hashes.
+.PP
+Attribute::Constant \- Make read-only variables via attribute
+.PP
+Scalar::Readonly \- Perl extension to the \f(CW\*(C`SvREADONLY\*(C'\fR scalar flag
+.PP
+Hash::Util \- A selection of general-utility hash subroutines (mostly
+to lock/unlock keys and values)
+.SH BUGS
+.IX Header "BUGS"
+Please report any bugs or feature requests via the \fBperlbug\fR\|(1) utility.
+.SH AUTHORS
+.IX Header "AUTHORS"
+Tom Phoenix, <\fIrootbeer@redcat.com\fR>, with help from
+many other folks.
+.PP
+Multiple constant declarations at once added by Casey West,
+<\fIcasey@geeknest.com\fR>.
+.PP
+Documentation mostly rewritten by Ilmari Karonen,
+<\fIperl@itz.pp.sci.fi\fR>.
+.PP
+This program is maintained by the Perl 5 Porters. 
+The CPAN distribution is maintained by Sébastien Aperghis-Tramoni
+<\fIsebastien@aperghis.net\fR>.
+.SH "COPYRIGHT & LICENSE"
+.IX Header "COPYRIGHT & LICENSE"
+Copyright (C) 1997, 1999 Tom Phoenix
+.PP
+This module is free software; you can redistribute it or modify it
+under the same terms as Perl itself.