Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 363 insertions, 0 deletions

diff --git a/upstream/fedora-rawhide/man1/perltrap.1 b/upstream/fedora-rawhide/man1/perltrap.1
new file mode 100644
index 00000000..ec49bf9e
--- /dev/null
+++ b/upstream/fedora-rawhide/man1/perltrap.1
@@ -0,0 +1,363 @@
+.\" -*- 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 "PERLTRAP 1"
+.TH PERLTRAP 1 2024-01-25 "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
+perltrap \- Perl traps for the unwary
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The biggest trap of all is forgetting to \f(CW\*(C`use warnings\*(C'\fR or use the \fB\-w\fR
+switch; see warnings and "\-w" in perlrun. The second biggest trap is not
+making your entire program runnable under \f(CW\*(C`use strict\*(C'\fR.  The third biggest
+trap is not reading the list of changes in this version of Perl; see
+perldelta.
+.SS "Awk Traps"
+.IX Subsection "Awk Traps"
+Accustomed \fBawk\fR users should take special note of the following:
+.IP \(bu 4
+A Perl program executes only once, not once for each input line.  You can
+do an implicit loop with \f(CW\*(C`\-n\*(C'\fR or \f(CW\*(C`\-p\*(C'\fR.
+.IP \(bu 4
+The English module, loaded via
+.Sp
+.Vb 1
+\&    use English;
+.Ve
+.Sp
+allows you to refer to special variables (like \f(CW$/\fR) with names (like
+\&\f(CW$RS\fR), as though they were in \fBawk\fR; see perlvar for details.
+.IP \(bu 4
+Semicolons are required after all simple statements in Perl (except
+at the end of a block).  Newline is not a statement delimiter.
+.IP \(bu 4
+Curly brackets are required on \f(CW\*(C`if\*(C'\fRs and \f(CW\*(C`while\*(C'\fRs.
+.IP \(bu 4
+Variables begin with "$", "@" or "%" in Perl.
+.IP \(bu 4
+Arrays index from 0.  Likewise string positions in \fBsubstr()\fR and
+\&\fBindex()\fR.
+.IP \(bu 4
+You have to decide whether your array has numeric or string indices.
+.IP \(bu 4
+Hash values do not spring into existence upon mere reference.
+.IP \(bu 4
+You have to decide whether you want to use string or numeric
+comparisons.
+.IP \(bu 4
+Reading an input line does not split it for you.  You get to split it
+to an array yourself.  And the \fBsplit()\fR operator has different
+arguments than \fBawk\fR's.
+.IP \(bu 4
+The current input line is normally in \f(CW$_\fR, not \f(CW$0\fR.  It generally does
+not have the newline stripped.  ($0 is the name of the program
+executed.)  See perlvar.
+.IP \(bu 4
+$<\fIdigit\fR> does not refer to fields\-\-it refers to substrings matched
+by the last match pattern.
+.IP \(bu 4
+The \fBprint()\fR statement does not add field and record separators unless
+you set \f(CW$,\fR and \f(CW\*(C`$\e\*(C'\fR.  You can set \f(CW$OFS\fR and \f(CW$ORS\fR if you're using
+the English module.
+.IP \(bu 4
+You must open your files before you print to them.
+.IP \(bu 4
+The range operator is "..", not comma.  The comma operator works as in
+C.
+.IP \(bu 4
+The match operator is "=~", not "~".  ("~" is the one's complement
+operator, as in C.)
+.IP \(bu 4
+The exponentiation operator is "**", not "^".  "^" is the XOR
+operator, as in C.  (You know, one could get the feeling that \fBawk\fR is
+basically incompatible with C.)
+.IP \(bu 4
+The concatenation operator is ".", not the null string.  (Using the
+null string would render \f(CW\*(C`/pat/ /pat/\*(C'\fR unparsable, because the third slash
+would be interpreted as a division operator\-\-the tokenizer is in fact
+slightly context sensitive for operators like "/", "?", and ">".
+And in fact, "." itself can be the beginning of a number.)
+.IP \(bu 4
+The \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`exit\*(C'\fR, and \f(CW\*(C`continue\*(C'\fR keywords work differently.
+.IP \(bu 4
+The following variables work differently:
+.Sp
+.Vb 10
+\&      Awk       Perl
+\&      ARGC      scalar @ARGV (compare with $#ARGV)
+\&      ARGV[0]   $0
+\&      FILENAME  $ARGV
+\&      FNR       $. \- something
+\&      FS        (whatever you like)
+\&      NF        $#Fld, or some such
+\&      NR        $.
+\&      OFMT      $#
+\&      OFS       $,
+\&      ORS       $\e
+\&      RLENGTH   length($&)
+\&      RS        $/
+\&      RSTART    length($\`)
+\&      SUBSEP    $;
+.Ve
+.IP \(bu 4
+You cannot set \f(CW$RS\fR to a pattern, only a string.
+.IP \(bu 4
+When in doubt, run the \fBawk\fR construct through \fBa2p\fR and see what it
+gives you.
+.SS "C/C++ Traps"
+.IX Subsection "C/C++ Traps"
+Cerebral C and C++ programmers should take note of the following:
+.IP \(bu 4
+Curly brackets are required on \f(CW\*(C`if\*(C'\fR's and \f(CW\*(C`while\*(C'\fR's.
+.IP \(bu 4
+You must use \f(CW\*(C`elsif\*(C'\fR rather than \f(CW\*(C`else if\*(C'\fR.
+.IP \(bu 4
+The \f(CW\*(C`break\*(C'\fR and \f(CW\*(C`continue\*(C'\fR keywords from C become in Perl \f(CW\*(C`last\*(C'\fR
+and \f(CW\*(C`next\*(C'\fR, respectively.  Unlike in C, these do \fInot\fR work within a
+\&\f(CW\*(C`do { } while\*(C'\fR construct.  See "Loop Control" in perlsyn.
+.IP \(bu 4
+The switch statement is called \f(CW\*(C`given\*(C'\fR/\f(CW\*(C`when\*(C'\fR and only available in
+perl 5.10 or newer.  See "Switch Statements" in perlsyn.
+.IP \(bu 4
+Variables begin with "$", "@" or "%" in Perl.
+.IP \(bu 4
+Comments begin with "#", not "/*" or "//".  Perl may interpret C/C++
+comments as division operators, unterminated regular expressions or
+the defined-or operator.
+.IP \(bu 4
+You can't take the address of anything, although a similar operator
+in Perl is the backslash, which creates a reference.
+.IP \(bu 4
+\&\f(CW\*(C`ARGV\*(C'\fR must be capitalized.  \f(CW$ARGV[0]\fR is C's \f(CW\*(C`argv[1]\*(C'\fR, and \f(CW\*(C`argv[0]\*(C'\fR
+ends up in \f(CW$0\fR.
+.IP \(bu 4
+System calls such as \fBlink()\fR, \fBunlink()\fR, \fBrename()\fR, etc. return nonzero for
+success, not 0. (\fBsystem()\fR, however, returns zero for success.)
+.IP \(bu 4
+Signal handlers deal with signal names, not numbers.  Use \f(CW\*(C`kill \-l\*(C'\fR
+to find their names on your system.
+.SS "JavaScript Traps"
+.IX Subsection "JavaScript Traps"
+Judicious JavaScript programmers should take note of the following:
+.IP \(bu 4
+In Perl, binary \f(CW\*(C`+\*(C'\fR is always addition.  \f(CW\*(C`$string1 + $string2\*(C'\fR converts
+both strings to numbers and then adds them.  To concatenate two strings,
+use the \f(CW\*(C`.\*(C'\fR operator.
+.IP \(bu 4
+The \f(CW\*(C`+\*(C'\fR unary operator doesn't do anything in Perl.  It exists to avoid
+syntactic ambiguities.
+.IP \(bu 4
+Unlike \f(CW\*(C`for...in\*(C'\fR, Perl's \f(CW\*(C`for\*(C'\fR (also spelled \f(CW\*(C`foreach\*(C'\fR) does not allow
+the left-hand side to be an arbitrary expression.  It must be a variable:
+.Sp
+.Vb 3
+\&   for my $variable (keys %hash) {
+\&        ...
+\&   }
+.Ve
+.Sp
+Furthermore, don't forget the \f(CW\*(C`keys\*(C'\fR in there, as
+\&\f(CW\*(C`foreach my $kv (%hash) {}\*(C'\fR iterates over the keys and values, and is
+generally not useful ($kv would be a key, then a value, and so on).
+.IP \(bu 4
+To iterate over the indices of an array, use \f(CW\*(C`foreach my $i (0 .. $#array)
+{}\*(C'\fR.  \f(CW\*(C`foreach my $v (@array) {}\*(C'\fR iterates over the values.
+.IP \(bu 4
+Perl requires braces following \f(CW\*(C`if\*(C'\fR, \f(CW\*(C`while\*(C'\fR, \f(CW\*(C`foreach\*(C'\fR, etc.
+.IP \(bu 4
+In Perl, \f(CW\*(C`else if\*(C'\fR is spelled \f(CW\*(C`elsif\*(C'\fR.
+.IP \(bu 4
+\&\f(CW\*(C`? :\*(C'\fR has higher precedence than assignment.  In JavaScript, one can
+write:
+.Sp
+.Vb 1
+\&    condition ? do_something() : variable = 3
+.Ve
+.Sp
+and the variable is only assigned if the condition is false.  In Perl, you
+need parentheses:
+.Sp
+.Vb 1
+\&    $condition ? do_something() : ($variable = 3);
+.Ve
+.Sp
+Or just use \f(CW\*(C`if\*(C'\fR.
+.IP \(bu 4
+Perl requires semicolons to separate statements.
+.IP \(bu 4
+Variables declared with \f(CW\*(C`my\*(C'\fR only affect code \fIafter\fR the declaration.
+You cannot write \f(CW\*(C`$x = 1; my $x;\*(C'\fR and expect the first assignment to
+affect the same variable.  It will instead assign to an \f(CW$x\fR declared
+previously in an outer scope, or to a global variable.
+.Sp
+Note also that the variable is not visible until the following
+\&\fIstatement\fR.  This means that in \f(CW\*(C`my $x = 1 + $x\*(C'\fR the second \f(CW$x\fR refers
+to one declared previously.
+.IP \(bu 4
+\&\f(CW\*(C`my\*(C'\fR variables are scoped to the current block, not to the current
+function.  If you write \f(CW\*(C`{my $x;} $x;\*(C'\fR, the second \f(CW$x\fR does not refer to
+the one declared inside the block.
+.IP \(bu 4
+An object's members cannot be made accessible as variables.  The closest
+Perl equivalent to \f(CW\*(C`with(object) { method() }\*(C'\fR is \f(CW\*(C`for\*(C'\fR, which can alias
+\&\f(CW$_\fR to the object:
+.Sp
+.Vb 3
+\&    for ($object) {
+\&        $_\->method;
+\&    }
+.Ve
+.IP \(bu 4
+The object or class on which a method is called is passed as one of the
+method's arguments, not as a separate \f(CW\*(C`this\*(C'\fR value.
+.SS "Sed Traps"
+.IX Subsection "Sed Traps"
+Seasoned \fBsed\fR programmers should take note of the following:
+.IP \(bu 4
+A Perl program executes only once, not once for each input line.  You can
+do an implicit loop with \f(CW\*(C`\-n\*(C'\fR or \f(CW\*(C`\-p\*(C'\fR.
+.IP \(bu 4
+Backreferences in substitutions use "$" rather than "\e".
+.IP \(bu 4
+The pattern matching metacharacters "(", ")", and "|" do not have backslashes
+in front.
+.IP \(bu 4
+The range operator is \f(CW\*(C`...\*(C'\fR, rather than comma.
+.SS "Shell Traps"
+.IX Subsection "Shell Traps"
+Sharp shell programmers should take note of the following:
+.IP \(bu 4
+The backtick operator does variable interpolation without regard to
+the presence of single quotes in the command.
+.IP \(bu 4
+The backtick operator does no translation of the return value, unlike \fBcsh\fR.
+.IP \(bu 4
+Shells (especially \fBcsh\fR) do several levels of substitution on each
+command line.  Perl does substitution in only certain constructs
+such as double quotes, backticks, angle brackets, and search patterns.
+.IP \(bu 4
+Shells interpret scripts a little bit at a time.  Perl compiles the
+entire program before executing it (except for \f(CW\*(C`BEGIN\*(C'\fR blocks, which
+execute at compile time).
+.IP \(bu 4
+The arguments are available via \f(CW@ARGV\fR, not \f(CW$1\fR, \f(CW$2\fR, etc.
+.IP \(bu 4
+The environment is not automatically made available as separate scalar
+variables.
+.IP \(bu 4
+The shell's \f(CW\*(C`test\*(C'\fR uses "=", "!=", "<" etc for string comparisons and "\-eq",
+"\-ne", "\-lt" etc for numeric comparisons. This is the reverse of Perl, which
+uses \f(CW\*(C`eq\*(C'\fR, \f(CW\*(C`ne\*(C'\fR, \f(CW\*(C`lt\*(C'\fR for string comparisons, and \f(CW\*(C`==\*(C'\fR, \f(CW\*(C`!=\*(C'\fR \f(CW\*(C`<\*(C'\fR etc
+for numeric comparisons.
+.SS "Perl Traps"
+.IX Subsection "Perl Traps"
+Practicing Perl Programmers should take note of the following:
+.IP \(bu 4
+Remember that many operations behave differently in a list
+context than they do in a scalar one.  See perldata for details.
+.IP \(bu 4
+Avoid barewords if you can, especially all lowercase ones.
+You can't tell by just looking at it whether a bareword is
+a function or a string.  By using quotes on strings and
+parentheses on function calls, you won't ever get them confused.
+.IP \(bu 4
+You cannot discern from mere inspection which builtins
+are unary operators (like \fBchop()\fR and \fBchdir()\fR)
+and which are list operators (like \fBprint()\fR and \fBunlink()\fR).
+(Unless prototyped, user-defined subroutines can \fBonly\fR be list
+operators, never unary ones.)  See perlop and perlsub.
+.IP \(bu 4
+People have a hard time remembering that some functions
+default to \f(CW$_\fR, or \f(CW@ARGV\fR, or whatever, but that others which
+you might expect to do not.
+.IP \(bu 4
+The <FH> construct is not the name of the filehandle, it is a readline
+operation on that handle.  The data read is assigned to \f(CW$_\fR only if the
+file read is the sole condition in a while loop:
+.Sp
+.Vb 3
+\&    while (<FH>)      { }
+\&    while (defined($_ = <FH>)) { }..
+\&    <FH>;  # data discarded!
+.Ve
+.IP \(bu 4
+Remember not to use \f(CW\*(C`=\*(C'\fR when you need \f(CW\*(C`=~\*(C'\fR;
+these two constructs are quite different:
+.Sp
+.Vb 2
+\&    $x =  /foo/;
+\&    $x =~ /foo/;
+.Ve
+.IP \(bu 4
+The \f(CW\*(C`do {}\*(C'\fR construct isn't a real loop that you can use
+loop control on.
+.IP \(bu 4
+Use \f(CWmy()\fR for local variables whenever you can get away with
+it (but see perlform for where you can't).
+Using \f(CWlocal()\fR actually gives a local value to a global
+variable, which leaves you open to unforeseen side-effects
+of dynamic scoping.
+.IP \(bu 4
+If you localize an exported variable in a module, its exported value will
+not change.  The local name becomes an alias to a new value but the
+external name is still an alias for the original.
+.PP
+As always, if any of these are ever officially declared as bugs,
+they'll be fixed and removed.