Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 1482 insertions, 0 deletions

diff --git a/upstream/fedora-40/man1/perldata.1 b/upstream/fedora-40/man1/perldata.1
new file mode 100644
index 00000000..f4562a7e
--- /dev/null
+++ b/upstream/fedora-40/man1/perldata.1
@@ -0,0 +1,1482 @@
+.\" -*- 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 "PERLDATA 1"
+.TH PERLDATA 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
+perldata \- Perl data types
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+.SS "Variable names"
+.IX Xref "variable, name variable name data type type"
+.IX Subsection "Variable names"
+Perl has three built-in data types: scalars, arrays of scalars, and
+associative arrays of scalars, known as "hashes".  A scalar is a 
+single string (of any size, limited only by the available memory),
+number, or a reference to something (which will be discussed
+in perlref).  Normal arrays are ordered lists of scalars indexed
+by number, starting with 0.  Hashes are unordered collections of scalar 
+values indexed by their associated string key.
+.PP
+Values are usually referred to by name, or through a named reference.
+The first character of the name tells you to what sort of data
+structure it refers.  The rest of the name tells you the particular
+value to which it refers.  Usually this name is a single \fIidentifier\fR,
+that is, a string beginning with a letter or underscore, and
+containing letters, underscores, and digits.  In some cases, it may
+be a chain of identifiers, separated by \f(CW\*(C`::\*(C'\fR (or by the deprecated \f(CW\*(C`\*(Aq\*(C'\fR);
+all but the last are interpreted as names of packages,
+to locate the namespace in which to look up the final identifier
+(see "Packages" in perlmod for details).  For a more in-depth discussion
+on identifiers, see "Identifier parsing".  It's possible to
+substitute for a simple identifier, an expression that produces a reference
+to the value at runtime.   This is described in more detail below
+and in perlref.
+.IX Xref "identifier"
+.PP
+Perl also has its own built-in variables whose names don't follow
+these rules.  They have strange names so they don't accidentally
+collide with one of your normal variables.  Strings that match
+parenthesized parts of a regular expression are saved under names
+containing only digits after the \f(CW\*(C`$\*(C'\fR (see perlop and perlre).
+In addition, several special variables that provide windows into
+the inner working of Perl have names containing punctuation characters.
+These are documented in perlvar.
+.IX Xref "variable, built-in"
+.PP
+Scalar values are always named with '$', even when referring to a
+scalar that is part of an array or a hash.  The '$' symbol works
+semantically like the English word "the" in that it indicates a
+single value is expected.
+.IX Xref "scalar"
+.PP
+.Vb 4
+\&    $days               # the simple scalar value "days"
+\&    $days[28]           # the 29th element of array @days
+\&    $days{\*(AqFeb\*(Aq}        # the \*(AqFeb\*(Aq value from hash %days
+\&    $#days              # the last index of array @days
+.Ve
+.PP
+Entire arrays (and slices of arrays and hashes) are denoted by '@',
+which works much as the word "these" or "those" does in English,
+in that it indicates multiple values are expected.
+.IX Xref "array"
+.PP
+.Vb 3
+\&    @days               # ($days[0], $days[1],... $days[n])
+\&    @days[3,4,5]        # same as ($days[3],$days[4],$days[5])
+\&    @days{\*(Aqa\*(Aq,\*(Aqc\*(Aq}      # same as ($days{\*(Aqa\*(Aq},$days{\*(Aqc\*(Aq})
+.Ve
+.PP
+Entire hashes are denoted by '%':
+.IX Xref "hash"
+.PP
+.Vb 1
+\&    %days               # (key1, val1, key2, val2 ...)
+.Ve
+.PP
+In addition, subroutines are named with an initial '&', though this
+is optional when unambiguous, just as the word "do" is often redundant
+in English.  Symbol table entries can be named with an initial '*',
+but you don't really care about that yet (if ever :\-).
+.PP
+Every variable type has its own namespace, as do several
+non-variable identifiers.  This means that you can, without fear
+of conflict, use the same name for a scalar variable, an array, or
+a hash\-\-or, for that matter, for a filehandle, a directory handle, a
+subroutine name, a format name, or a label.  This means that \f(CW$foo\fR
+and \f(CW@foo\fR are two different variables.  It also means that \f(CW$foo[1]\fR
+is a part of \f(CW@foo\fR, not a part of \f(CW$foo\fR.  This may seem a bit weird,
+but that's okay, because it is weird.
+.IX Xref "namespace"
+.PP
+Because variable references always start with '$', '@', or '%', the
+"reserved" words aren't in fact reserved with respect to variable
+names.  They \fIare\fR reserved with respect to labels and filehandles,
+however, which don't have an initial special character.  You can't
+have a filehandle named "log", for instance.  Hint: you could say
+\&\f(CW\*(C`open(LOG,\*(Aqlogfile\*(Aq)\*(C'\fR rather than \f(CW\*(C`open(log,\*(Aqlogfile\*(Aq)\*(C'\fR.  Using
+uppercase filehandles also improves readability and protects you
+from conflict with future reserved words.  Case \fIis\fR significant\-\-"FOO",
+"Foo", and "foo" are all different names.  Names that start with a
+letter or underscore may also contain digits and underscores.
+.IX Xref "identifier, case sensitivity case"
+.PP
+It is possible to replace such an alphanumeric name with an expression
+that returns a reference to the appropriate type.  For a description
+of this, see perlref.
+.PP
+Names that start with a digit may contain only more digits.  Names
+that do not start with a letter, underscore, digit or a caret are
+limited to one character, e.g.,  \f(CW$%\fR or
+\&\f(CW$$\fR.  (Most of these one character names have a predefined
+significance to Perl.  For instance, \f(CW$$\fR is the current process
+id.  And all such names are reserved for Perl's possible use.)
+.SS "Identifier parsing"
+.IX Xref "identifiers"
+.IX Subsection "Identifier parsing"
+Up until Perl 5.18, the actual rules of what a valid identifier
+was were a bit fuzzy.  However, in general, anything defined here should
+work on previous versions of Perl, while the opposite \-\- edge cases
+that work in previous versions, but aren't defined here \-\- probably
+won't work on newer versions.
+As an important side note, please note that the following only applies
+to bareword identifiers as found in Perl source code, not identifiers
+introduced through symbolic references, which have much fewer
+restrictions.
+If working under the effect of the \f(CW\*(C`use utf8;\*(C'\fR pragma, the following
+rules apply:
+.PP
+.Vb 2
+\&    / (?[ ( \ep{Word} & \ep{XID_Start} ) + [_] ])
+\&      (?[ ( \ep{Word} & \ep{XID_Continue} ) ]) *    /x
+.Ve
+.PP
+That is, a "start" character followed by any number of "continue"
+characters.  Perl requires every character in an identifier to also
+match \f(CW\*(C`\ew\*(C'\fR (this prevents some problematic cases); and Perl
+additionally accepts identifier names beginning with an underscore.
+.PP
+If not under \f(CW\*(C`use utf8\*(C'\fR, the source is treated as ASCII + 128 extra
+generic characters, and identifiers should match
+.PP
+.Vb 1
+\&    / (?aa) (?!\ed) \ew+ /x
+.Ve
+.PP
+That is, any word character in the ASCII range, as long as the first
+character is not a digit.
+.PP
+There are two package separators in Perl: A double colon (\f(CW\*(C`::\*(C'\fR) and a single
+quote (\f(CW\*(C`\*(Aq\*(C'\fR).  Use of \f(CW\*(C`\*(Aq\*(C'\fR as the package separator is deprecated and will be
+removed in Perl 5.40.  Normal identifiers can start or end with a double
+colon, and can contain several parts delimited by double colons.  Single
+quotes have similar rules, but with the exception that they are not legal at
+the end of an identifier: That is, \f(CW\*(C`$\*(Aqfoo\*(C'\fR and \f(CW\*(C`$foo\*(Aqbar\*(C'\fR are legal, but
+\&\f(CW\*(C`$foo\*(Aqbar\*(Aq\*(C'\fR is not.
+.PP
+Additionally, if the identifier is preceded by a sigil \-\-
+that is, if the identifier is part of a variable name \-\- it
+may optionally be enclosed in braces.
+.PP
+While you can mix double colons with singles quotes, the quotes must come
+after the colons: \f(CW\*(C`$::::\*(Aqfoo\*(C'\fR and \f(CW\*(C`$foo::\*(Aqbar\*(C'\fR are legal, but \f(CW\*(C`$::\*(Aq::foo\*(C'\fR
+and \f(CW\*(C`$foo\*(Aq::bar\*(C'\fR are not.
+.PP
+Put together, a grammar to match a basic identifier becomes
+.PP
+.Vb 10
+\& /
+\&  (?(DEFINE)
+\&      (?<variable>
+\&          (?&sigil)
+\&          (?:
+\&                  (?&normal_identifier)
+\&              |   \e{ \es* (?&normal_identifier) \es* \e}
+\&          )
+\&      )
+\&      (?<normal_identifier>
+\&          (?: :: )* \*(Aq?
+\&           (?&basic_identifier)
+\&           (?: (?= (?: :: )+ \*(Aq? | (?: :: )* \*(Aq ) (?&normal_identifier) )?
+\&          (?: :: )*
+\&      )
+\&      (?<basic_identifier>
+\&        # is use utf8 on?
+\&          (?(?{ (caller(0))[8] & $utf8::hint_bits })
+\&              (?&Perl_XIDS) (?&Perl_XIDC)*
+\&            | (?aa) (?!\ed) \ew+
+\&          )
+\&      )
+\&      (?<sigil> [&*\e$\e@\e%])
+\&      (?<Perl_XIDS> (?[ ( \ep{Word} & \ep{XID_Start} ) + [_] ]) )
+\&      (?<Perl_XIDC> (?[ \ep{Word} & \ep{XID_Continue} ]) )
+\&  )
+\& /x
+.Ve
+.PP
+Meanwhile, special identifiers don't follow the above rules; For the most
+part, all of the identifiers in this category have a special meaning given
+by Perl.  Because they have special parsing rules, these generally can't be
+fully-qualified.  They come in six forms (but don't use forms 5 and 6):
+.IP 1. 4
+A sigil, followed solely by digits matching \f(CW\*(C`\ep{POSIX_Digit}\*(C'\fR, like
+\&\f(CW$0\fR, \f(CW$1\fR, or \f(CW$10000\fR.
+.IP 2. 4
+A sigil followed by a single character matching the \f(CW\*(C`\ep{POSIX_Punct}\*(C'\fR
+property, like \f(CW$!\fR or \f(CW\*(C`%+\*(C'\fR, except the character \f(CW"{"\fR doesn't work.
+.IP 3. 4
+A sigil, followed by a caret and any one of the characters
+\&\f(CW\*(C`[][A\-Z^_?\e]\*(C'\fR, like \f(CW$^V\fR or \f(CW$^]\fR.
+.IP 4. 4
+Similar to the above, a sigil, followed by bareword text in braces,
+where the first character is a caret.  The next character is any one of
+the characters \f(CW\*(C`[][A\-Z^_?\e]\*(C'\fR, followed by ASCII word characters.  An
+example is \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR.
+.IP 5. 4
+A sigil, followed by any single character in the range \f(CW\*(C`[\exA1\-\exAC\exAE\-\exFF]\*(C'\fR
+when not under \f(CW"use\ utf8"\fR.  (Under \f(CW"use\ utf8"\fR, the normal
+identifier rules given earlier in this section apply.)  Use of
+non-graphic characters (the C1 controls, the NO-BREAK SPACE, and the
+SOFT HYPHEN) has been disallowed since v5.26.0.
+The use of the other characters is unwise, as these are all
+reserved to have special meaning to Perl, and none of them currently
+do have special meaning, though this could change without notice.
+.Sp
+Note that an implication of this form is that there are identifiers only
+legal under \f(CW"use\ utf8"\fR, and vice-versa, for example the identifier
+\&\f(CW\*(C`$état\*(C'\fR is legal under \f(CW"use\ utf8"\fR, but is otherwise
+considered to be the single character variable \f(CW$é\fR followed by
+the bareword \f(CW"tat"\fR, the combination of which is a syntax error.
+.IP 6. 4
+This is a combination of the previous two forms.  It is valid only when
+not under \f(CW"use\ utf8"\fR (normal identifier rules apply when under
+\&\f(CW"use\ utf8"\fR).  The form is a sigil, followed by text in braces,
+where the first character is any one of the characters in the range
+\&\f(CW\*(C`[\ex80\-\exFF]\*(C'\fR followed by ASCII word characters up to the trailing
+brace.
+.Sp
+The same caveats as the previous form apply:  The non-graphic
+characters are no longer allowed with "use\ utf8", it is unwise
+to use this form at all, and utf8ness makes a big difference.
+.PP
+Prior to Perl v5.24, non-graphical ASCII control characters were also
+allowed in some situations; this had been deprecated since v5.20.
+.SS Context
+.IX Xref "context scalar context list context"
+.IX Subsection "Context"
+The interpretation of operations and values in Perl sometimes depends
+on the requirements of the context around the operation or value.
+There are two major contexts: list and scalar.  Certain operations
+return list values in contexts wanting a list, and scalar values
+otherwise.  If this is true of an operation it will be mentioned in
+the documentation for that operation.  In other words, Perl overloads
+certain operations based on whether the expected return value is
+singular or plural.  Some words in English work this way, like "fish"
+and "sheep".
+.PP
+In a reciprocal fashion, an operation provides either a scalar or a
+list context to each of its arguments.  For example, if you say
+.PP
+.Vb 1
+\&    int( <STDIN> )
+.Ve
+.PP
+the integer operation provides scalar context for the <>
+operator, which responds by reading one line from STDIN and passing it
+back to the integer operation, which will then find the integer value
+of that line and return that.  If, on the other hand, you say
+.PP
+.Vb 1
+\&    sort( <STDIN> )
+.Ve
+.PP
+then the sort operation provides list context for <>, which
+will proceed to read every line available up to the end of file, and
+pass that list of lines back to the sort routine, which will then
+sort those lines and return them as a list to whatever the context
+of the sort was.
+.PP
+Assignment is a little bit special in that it uses its left argument
+to determine the context for the right argument.  Assignment to a
+scalar evaluates the right-hand side in scalar context, while
+assignment to an array or hash evaluates the righthand side in list
+context.  Assignment to a list (or slice, which is just a list
+anyway) also evaluates the right-hand side in list context.
+.PP
+When you use the \f(CW\*(C`use warnings\*(C'\fR pragma or Perl's \fB\-w\fR command-line 
+option, you may see warnings
+about useless uses of constants or functions in "void context".
+Void context just means the value has been discarded, such as a
+statement containing only \f(CW\*(C`"fred";\*(C'\fR or \f(CW\*(C`getpwuid(0);\*(C'\fR.  It still
+counts as scalar context for functions that care whether or not
+they're being called in list context.
+.PP
+User-defined subroutines may choose to care whether they are being
+called in a void, scalar, or list context.  Most subroutines do not
+need to bother, though.  That's because both scalars and lists are
+automatically interpolated into lists.  See "wantarray" in perlfunc
+for how you would dynamically discern your function's calling
+context.
+.SS "Scalar values"
+.IX Xref "scalar number string reference"
+.IX Subsection "Scalar values"
+All data in Perl is a scalar, an array of scalars, or a hash of
+scalars.  A scalar may contain one single value in any of three
+different flavors: a number, a string, or a reference.  In general,
+conversion from one form to another is transparent.  Although a
+scalar may not directly hold multiple values, it may contain a
+reference to an array or hash which in turn contains multiple values.
+.PP
+Scalars aren't necessarily one thing or another.  There's no place
+to declare a scalar variable to be of type "string", type "number",
+type "reference", or anything else.  Because of the automatic
+conversion of scalars, operations that return scalars don't need
+to care (and in fact, cannot care) whether their caller is looking
+for a string, a number, or a reference.  Perl is a contextually
+polymorphic language whose scalars can be strings, numbers, or
+references (which includes objects).  Although strings and numbers
+are considered pretty much the same thing for nearly all purposes,
+references are strongly-typed, uncastable pointers with builtin
+reference-counting and destructor invocation.
+.PP
+       
+ 
+A scalar value is interpreted as FALSE in the Boolean sense
+if it is undefined, the null string or the number 0 (or its
+string equivalent, "0"), and TRUE if it is anything else.  The
+Boolean context is just a special kind of scalar context where no 
+conversion to a string or a number is ever performed.
+Negation of a true value by \f(CW\*(C`!\*(C'\fR or \f(CW\*(C`not\*(C'\fR returns a special false value.
+When evaluated as a string it is treated as \f(CW""\fR, but as a number, it
+is treated as 0.  Most Perl operators
+that return true or false behave this way.
+.IX Xref "truth falsehood true false ! not negation 0 boolean bool"
+.PP
+There are actually two varieties of null strings (sometimes referred
+to as "empty" strings), a defined one and an undefined one.  The
+defined version is just a string of length zero, such as \f(CW""\fR.
+The undefined version is the value that indicates that there is
+no real value for something, such as when there was an error, or
+at end of file, or when you refer to an uninitialized variable or
+element of an array or hash.  Although in early versions of Perl,
+an undefined scalar could become defined when first used in a
+place expecting a defined value, this no longer happens except for
+rare cases of autovivification as explained in perlref.  You can
+use the \fBdefined()\fR operator to determine whether a scalar value is
+defined (this has no meaning on arrays or hashes), and the \fBundef()\fR
+operator to produce an undefined value.
+.IX Xref "defined undefined undef null string, null"
+.PP
+To find out whether a given string is a valid non-zero number, it's
+sometimes enough to test it against both numeric 0 and also lexical
+"0" (although this will cause noises if warnings are on).  That's 
+because strings that aren't numbers count as 0, just as they do in \fBawk\fR:
+.PP
+.Vb 3
+\&    if ($str == 0 && $str ne "0")  {
+\&        warn "That doesn\*(Aqt look like a number";
+\&    }
+.Ve
+.PP
+That method may be best because otherwise you won't treat IEEE
+notations like \f(CW\*(C`NaN\*(C'\fR or \f(CW\*(C`Infinity\*(C'\fR properly.  At other times, you
+might prefer to determine whether string data can be used numerically
+by calling the \fBPOSIX::strtod()\fR function or by inspecting your string
+with a regular expression (as documented in perlre).
+.PP
+.Vb 8
+\&    warn "has nondigits"        if     /\eD/;
+\&    warn "not a natural number" unless /^\ed+$/;             # rejects \-3
+\&    warn "not an integer"       unless /^\-?\ed+$/;           # rejects +3
+\&    warn "not an integer"       unless /^[+\-]?\ed+$/;
+\&    warn "not a decimal number" unless /^\-?\ed+\e.?\ed*$/;     # rejects .2
+\&    warn "not a decimal number" unless /^\-?(?:\ed+(?:\e.\ed*)?|\e.\ed+)$/;
+\&    warn "not a C float"
+\&        unless /^([+\-]?)(?=\ed|\e.\ed)\ed*(\e.\ed*)?([Ee]([+\-]?\ed+))?$/;
+.Ve
+.PP
+The length of an array is a scalar value.  You may find the length
+of array \f(CW@days\fR by evaluating \f(CW$#days\fR, as in \fBcsh\fR.  However, this
+isn't the length of the array; it's the subscript of the last element,
+which is a different value since there is ordinarily a 0th element.
+Assigning to \f(CW$#days\fR actually changes the length of the array.
+Shortening an array this way destroys intervening values.  Lengthening
+an array that was previously shortened does not recover values
+that were in those elements.
+.IX Xref "$# array, length"
+.PP
+You can also gain some minuscule measure of efficiency by pre-extending
+an array that is going to get big.  You can also extend an array
+by assigning to an element that is off the end of the array.  You
+can truncate an array down to nothing by assigning the null list
+() to it.  The following are equivalent:
+.PP
+.Vb 2
+\&    @whatever = ();
+\&    $#whatever = \-1;
+.Ve
+.PP
+If you evaluate an array in scalar context, it returns the length
+of the array.  (Note that this is not true of lists, which return
+the last value, like the C comma operator, nor of built-in functions,
+which return whatever they feel like returning.)  The following is
+always true:
+.IX Xref "array, length"
+.PP
+.Vb 1
+\&    scalar(@whatever) == $#whatever + 1;
+.Ve
+.PP
+Some programmers choose to use an explicit conversion so as to 
+leave nothing to doubt:
+.PP
+.Vb 1
+\&    $element_count = scalar(@whatever);
+.Ve
+.PP
+If you evaluate a hash in scalar context, it returns a false value if
+the hash is empty.  If there are any key/value pairs, it returns a
+true value.  A more precise definition is version dependent.
+.PP
+Prior to Perl 5.25 the value returned was a string consisting of the
+number of used buckets and the number of allocated buckets, separated
+by a slash.  This is pretty much useful only to find out whether
+Perl's internal hashing algorithm is performing poorly on your data
+set.  For example, you stick 10,000 things in a hash, but evaluating
+\&\f(CW%HASH\fR in scalar context reveals \f(CW"1/16"\fR, which means only one out
+of sixteen buckets has been touched, and presumably contains all
+10,000 of your items.  This isn't supposed to happen.
+.PP
+As of Perl 5.25 the return was changed to be the count of keys in the
+hash. If you need access to the old behavior you can use
+\&\f(CWHash::Util::bucket_ratio()\fR instead.
+.PP
+If a tied hash is evaluated in scalar context, the \f(CW\*(C`SCALAR\*(C'\fR method is
+called (with a fallback to \f(CW\*(C`FIRSTKEY\*(C'\fR).
+.IX Xref "hash, scalar context hash, bucket bucket"
+.PP
+You can preallocate space for a hash by assigning to the \fBkeys()\fR function.
+This rounds up the allocated buckets to the next power of two:
+.PP
+.Vb 1
+\&    keys(%users) = 1000;                # allocate 1024 buckets
+.Ve
+.SS "Scalar value constructors"
+.IX Xref "scalar, literal scalar, constant"
+.IX Subsection "Scalar value constructors"
+Numeric literals are specified in any of the following floating point or
+integer formats:
+.PP
+.Vb 11
+\& 12345
+\& 12345.67
+\& .23E\-10             # a very small number
+\& 3.14_15_92          # a very important number
+\& 4_294_967_296       # underscore for legibility
+\& 0xff                # hex
+\& 0xdead_beef         # more hex
+\& 0377                # octal (only numbers, begins with 0)
+\& 0o12_345            # alternative octal (introduced in Perl 5.33.5)
+\& 0b011011            # binary
+\& 0x1.999ap\-4         # hexadecimal floating point (the \*(Aqp\*(Aq is required)
+.Ve
+.PP
+You are allowed to use underscores (underbars) in numeric literals
+between digits for legibility (but not multiple underscores in a row:
+\&\f(CW\*(C`23_\|_500\*(C'\fR is not legal; \f(CW\*(C`23_500\*(C'\fR is).
+You could, for example, group binary
+digits by threes (as for a Unix-style mode argument such as 0b110_100_100)
+or by fours (to represent nibbles, as in 0b1010_0110) or in other groups.
+.IX Xref "number, literal"
+.PP
+String literals are usually delimited by either single or double
+quotes.  They work much like quotes in the standard Unix shells:
+double-quoted string literals are subject to backslash and variable
+substitution; single-quoted strings are not (except for \f(CW\*(C`\e\*(Aq\*(C'\fR and
+\&\f(CW\*(C`\e\e\*(C'\fR).  The usual C\-style backslash rules apply for making
+characters such as newline, tab, etc., as well as some more exotic
+forms.  See "Quote and Quote-like Operators" in perlop for a list.
+.IX Xref "string, literal"
+.PP
+Hexadecimal, octal, or binary, representations in string literals
+(e.g. '0xff') are not automatically converted to their integer
+representation.  The \fBhex()\fR and \fBoct()\fR functions make these conversions
+for you.  See "hex" in perlfunc and "oct" in perlfunc for more details.
+.PP
+Hexadecimal floating point can start just like a hexadecimal literal,
+and it can be followed by an optional fractional hexadecimal part,
+but it must be followed by \f(CW\*(C`p\*(C'\fR, an optional sign, and a power of two.
+The format is useful for accurately presenting floating point values,
+avoiding conversions to or from decimal floating point, and therefore
+avoiding possible loss in precision.  Notice that while most current
+platforms use the 64\-bit IEEE 754 floating point, not all do.  Another
+potential source of (low-order) differences are the floating point
+rounding modes, which can differ between CPUs, operating systems,
+and compilers, and which Perl doesn't control.
+.PP
+You can also embed newlines directly in your strings, i.e., they can end
+on a different line than they begin.  This is nice, but if you forget
+your trailing quote, the error will not be reported until Perl finds
+another line containing the quote character, which may be much further
+on in the script.  Variable substitution inside strings is limited to
+scalar variables, arrays, and array or hash slices.  (In other words,
+names beginning with $ or @, followed by an optional bracketed
+expression as a subscript.)  The following code segment prints out "The
+price is \f(CW$100\fR."
+.IX Xref "interpolation"
+.PP
+.Vb 2
+\&    $Price = \*(Aq$100\*(Aq;    # not interpolated
+\&    print "The price is $Price.\en";     # interpolated
+.Ve
+.PP
+There is no double interpolation in Perl, so the \f(CW$100\fR is left as is.
+.PP
+By default floating point numbers substituted inside strings use the
+dot (".")  as the decimal separator.  If \f(CW\*(C`use locale\*(C'\fR is in effect,
+and \fBPOSIX::setlocale()\fR has been called, the character used for the
+decimal separator is affected by the LC_NUMERIC locale.
+See perllocale and POSIX.
+.PP
+\fIDemarcated variable names using braces\fR
+.IX Subsection "Demarcated variable names using braces"
+.PP
+As in some shells, you can enclose the variable name in braces as a
+demarcator to disambiguate it from following alphanumerics and
+underscores or other text. You must also do this when interpolating a
+variable into a string to separate the variable name from a following
+double-colon or an apostrophe since these would be otherwise treated as
+a package separator:
+.IX Xref "interpolation"
+.PP
+.Vb 3
+\&    $who = "Larry";
+\&    print PASSWD "${who}::0:0:Superuser:/:/bin/perl\en";
+\&    print "We use ${who}speak when ${who}\*(Aqs here.\en";
+.Ve
+.PP
+Without the braces, Perl would have looked for a \f(CW$whospeak\fR, a
+\&\f(CW$who::0\fR, and a \f(CW\*(C`$who\*(Aqs\*(C'\fR variable.  The last two would be the
+\&\f(CW$0\fR and the \f(CW$s\fR variables in the (presumably) non-existent package
+\&\f(CW\*(C`who\*(C'\fR.
+.PP
+In fact, a simple identifier within such curly braces is forced to be a
+string, and likewise within a hash subscript. Neither need quoting. Our
+earlier example, \f(CW$days{\*(AqFeb\*(Aq}\fR can be written as \f(CW$days{Feb}\fR and the
+quotes will be assumed automatically. But anything more complicated in
+the subscript will be interpreted as an expression. This means for
+example that \f(CW\*(C`$version{2.0}++\*(C'\fR is equivalent to \f(CW\*(C`$version{2}++\*(C'\fR, not
+to \f(CW\*(C`$version{\*(Aq2.0\*(Aq}++\*(C'\fR.
+.PP
+There is a similar problem with interpolation with text that looks like
+array or hash access notation. Placing a simple variable like \f(CW$who\fR
+immediately in front of text like \f(CW"[1]"\fR or \f(CW"{foo}"\fR would cause the
+variable to be interpolated as accessing an element of \f(CW@who\fR or a
+value stored in \f(CW%who\fR:
+.PP
+.Vb 2
+\&    $who = "Larry Wall";
+\&    print "$who[1] is the father of Perl.\en";
+.Ve
+.PP
+would attempt to access index 1 of an array named \f(CW@who\fR. Again, using
+braces will prevent this from happening:
+.PP
+.Vb 2
+\&    $who = "Larry Wall";
+\&    print "${who}[1] is the father of Perl.\en";
+.Ve
+.PP
+will be treated the same as
+.PP
+.Vb 2
+\&    $who = "Larry Wall";
+\&    print $who . "[1] is the father of Perl.\en";
+.Ve
+.PP
+This notation also applies to more complex variable descriptions,
+such as array or hash access with subscripts. For instance
+.PP
+.Vb 2
+\&    @name = qw(Larry Curly Moe);
+\&    print "Also ${name[0]}[1] was a member\en";
+.Ve
+.PP
+Without the braces the above example would be parsed as a two level
+array subscript in the \f(CW@name\fR array, and under \f(CW\*(C`use strict\*(C'\fR would
+likely produce a fatal exception, as it would be parsed like this:
+.PP
+.Vb 1
+\&    print "Also " . $name[0][1] . " was a member\en";
+.Ve
+.PP
+and not as the intended:
+.PP
+.Vb 1
+\&    print "Also " . $name[0] . "[1] was a member\en";
+.Ve
+.PP
+A similar result may be derived by using a backslash on the first
+character of the subscript or package notation that is not part of
+the variable you want to access. Thus the above example could also
+be written:
+.PP
+.Vb 2
+\&    @name = qw(Larry Curly Moe);
+\&    print "Also $name[0]\e[1] was a member\en";
+.Ve
+.PP
+however for some special variables (multi character caret variables) the
+demarcated form using curly braces is the \fBonly\fR way you can reference
+the variable at all, and the only way you can access a subscript of the
+variable via interpolation.
+.PP
+Consider the magic array \f(CW\*(C`@{^CAPTURE}\*(C'\fR which is populated by the
+regex engine with the contents of all of the capture buffers in a
+pattern (see perlvar and perlre). The \fBonly\fR way you can
+access one of these members inside of a string is via the braced
+(demarcated) form:
+.PP
+.Vb 2
+\&    "abc"=~/(.)(.)(.)/
+\&        and print "Second buffer is ${^CAPTURE[1]}";
+.Ve
+.PP
+is equivalent to
+.PP
+.Vb 2
+\&    "abc"=~/(.)(.)(.)/
+\&        and print "Second buffer is " . ${^CAPTURE}[1];
+.Ve
+.PP
+Saying \f(CW\*(C`@^CAPTURE\*(C'\fR is a syntax error, so it \fBmust\fR be referenced as
+\&\f(CW\*(C`@{^CAPTURE}\*(C'\fR, and to access one of its elements in normal code you
+would write \f(CW\*(C` ${^CAPTURE}[1] \*(C'\fR. However when interpolating in a string
+\&\f(CW"${^CAPTURE}[1]"\fR would be equivalent to \f(CW\*(C`${^CAPTURE} . "[1]"\*(C'\fR,
+which does not even refer to the same variable! Thus the subscripts must
+\&\fBalso\fR be placed \fBinside\fR of the braces: \f(CW"${^CAPTURE[1]}"\fR.
+.PP
+The demarcated form using curly braces can be used with all the
+different types of variable access, including array and hash slices. For
+instance code like the following:
+.PP
+.Vb 3
+\&    @name = qw(Larry Curly Moe);
+\&    local $" = " and ";
+\&    print "My favorites were @{name[1,2]}.\en";
+.Ve
+.PP
+would output
+.PP
+.Vb 1
+\&    My favorites were Curly and Moe.
+.Ve
+.PP
+\fISpecial floating point: infinity (Inf) and not-a-number (NaN)\fR
+.IX Subsection "Special floating point: infinity (Inf) and not-a-number (NaN)"
+.PP
+Floating point values include the special values \f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR,
+for infinity and not-a-number.  The infinity can be also negative.
+.PP
+The infinity is the result of certain math operations that overflow
+the floating point range, like 9**9**9.  The not-a-number is the
+result when the result is undefined or unrepresentable.  Though note
+that you cannot get \f(CW\*(C`NaN\*(C'\fR from some common "undefined" or
+"out-of-range" operations like dividing by zero, or square root of
+a negative number, since Perl generates fatal errors for those.
+.PP
+The infinity and not-a-number have their own special arithmetic rules.
+The general rule is that they are "contagious": \f(CW\*(C`Inf\*(C'\fR plus one is
+\&\f(CW\*(C`Inf\*(C'\fR, and \f(CW\*(C`NaN\*(C'\fR plus one is \f(CW\*(C`NaN\*(C'\fR.  Where things get interesting
+is when you combine infinities and not-a-numbers: \f(CW\*(C`Inf\*(C'\fR minus \f(CW\*(C`Inf\*(C'\fR
+and \f(CW\*(C`Inf\*(C'\fR divided by \f(CW\*(C`Inf\*(C'\fR are \f(CW\*(C`NaN\*(C'\fR (while \f(CW\*(C`Inf\*(C'\fR plus \f(CW\*(C`Inf\*(C'\fR is
+\&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`Inf\*(C'\fR times \f(CW\*(C`Inf\*(C'\fR is \f(CW\*(C`Inf\*(C'\fR).  \f(CW\*(C`NaN\*(C'\fR is also curious
+in that it does not equal any number, \fIincluding\fR itself:
+\&\f(CW\*(C`NaN\*(C'\fR != \f(CW\*(C`NaN\*(C'\fR.
+.PP
+Perl doesn't understand \f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR as numeric literals, but
+you can have them as strings, and Perl will convert them as needed:
+"Inf" + 1.  (You can, however, import them from the POSIX extension;
+\&\f(CW\*(C`use POSIX qw(Inf NaN);\*(C'\fR and then use them as literals.)
+.PP
+Note that on input (string to number) Perl accepts \f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR
+in many forms.   Case is ignored, and the Win32\-specific forms like
+\&\f(CW\*(C`1.#INF\*(C'\fR are understood, but on output the values are normalized to
+\&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`NaN\*(C'\fR.
+.PP
+\fIVersion Strings\fR
+.IX Xref "version string vstring v-string"
+.IX Subsection "Version Strings"
+.PP
+A literal of the form \f(CW\*(C`v1.20.300.4000\*(C'\fR is parsed as a string composed
+of characters with the specified ordinals.  This form, known as
+v\-strings, provides an alternative, more readable way to construct
+strings, rather than use the somewhat less readable interpolation form
+\&\f(CW"\ex{1}\ex{14}\ex{12c}\ex{fa0}"\fR.  This is useful for representing
+Unicode strings, and for comparing version "numbers" using the string
+comparison operators, \f(CW\*(C`cmp\*(C'\fR, \f(CW\*(C`gt\*(C'\fR, \f(CW\*(C`lt\*(C'\fR etc.  If there are two or
+more dots in the literal, the leading \f(CW\*(C`v\*(C'\fR may be omitted.
+.PP
+.Vb 3
+\&    print v9786;              # prints SMILEY, "\ex{263a}"
+\&    print v102.111.111;       # prints "foo"
+\&    print 102.111.111;        # same
+.Ve
+.PP
+Such literals are accepted by both \f(CW\*(C`require\*(C'\fR and \f(CW\*(C`use\*(C'\fR for
+doing a version check.  Note that using the v\-strings for IPv4
+addresses is not portable unless you also use the
+\&\fBinet_aton()\fR/\fBinet_ntoa()\fR routines of the Socket package.
+.PP
+Note that since Perl 5.8.1 the single-number v\-strings (like \f(CW\*(C`v65\*(C'\fR)
+are not v\-strings before the \f(CW\*(C`=>\*(C'\fR operator (which is usually used
+to separate a hash key from a hash value); instead they are interpreted
+as literal strings ('v65').  They were v\-strings from Perl 5.6.0 to
+Perl 5.8.0, but that caused more confusion and breakage than good.
+Multi-number v\-strings like \f(CW\*(C`v65.66\*(C'\fR and \f(CW65.66.67\fR continue to
+be v\-strings always.
+.PP
+\fISpecial Literals\fR
+.IX Xref "special literal __END__ __DATA__ END DATA end data ^D ^Z"
+.IX Subsection "Special Literals"
+.PP
+The special literals _\|_FILE_\|_, _\|_LINE_\|_, and _\|_PACKAGE_\|_
+represent the current filename, line number, and package name at that
+point in your program.  _\|_SUB_\|_ gives a reference to the current
+subroutine.  They may be used only as separate tokens; they
+will not be interpolated into strings.  If there is no current package
+(due to an empty \f(CW\*(C`package;\*(C'\fR directive), _\|_PACKAGE_\|_ is the undefined
+value.  (But the empty \f(CW\*(C`package;\*(C'\fR is no longer supported, as of version
+5.10.)  Outside of a subroutine, _\|_SUB_\|_ is the undefined value.  _\|_SUB_\|_
+is only available in 5.16 or higher, and only with a \f(CW\*(C`use v5.16\*(C'\fR or
+\&\f(CW\*(C`use feature "current_sub"\*(C'\fR declaration.
+.IX Xref "__FILE__ __LINE__ __PACKAGE__ __SUB__ line file package"
+.PP
+The two control characters ^D and ^Z, and the tokens _\|_END_\|_ and _\|_DATA_\|_
+may be used to indicate the logical end of the script before the actual
+end of file.  Any following text is ignored by the interpreter unless
+read by the program as described below.
+.PP
+Text after _\|_DATA_\|_ may be read via the filehandle \f(CW\*(C`PACKNAME::DATA\*(C'\fR,
+where \f(CW\*(C`PACKNAME\*(C'\fR is the package that was current when the _\|_DATA_\|_
+token was encountered.  The filehandle is left open pointing to the
+line after _\|_DATA_\|_.  The program should \f(CW\*(C`close DATA\*(C'\fR when it is done
+reading from it.  (Leaving it open leaks filehandles if the module is
+reloaded for any reason, so it's a safer practice to close it.)  For
+compatibility with older scripts written before _\|_DATA_\|_ was
+introduced, _\|_END_\|_ behaves like _\|_DATA_\|_ in the top level script (but
+not in files loaded with \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`do\*(C'\fR) and leaves the remaining
+contents of the file accessible via \f(CW\*(C`main::DATA\*(C'\fR.
+.PP
+.Vb 4
+\&  while (my $line = <DATA>) { print $line; }
+\&  close DATA;
+\&  _\|_DATA_\|_
+\&  Hello world.
+.Ve
+.PP
+The \f(CW\*(C`DATA\*(C'\fR file handle by default has whatever PerlIO layers were
+in place when Perl read the file to parse the source.  Normally that
+means that the file is being read bytewise, as if it were encoded in
+Latin\-1, but there are two major ways for it to be otherwise.  Firstly,
+if the \f(CW\*(C`_\|_END_\|_\*(C'\fR/\f(CW\*(C`_\|_DATA_\|_\*(C'\fR token is in the scope of a \f(CW\*(C`use utf8\*(C'\fR
+pragma then the \f(CW\*(C`DATA\*(C'\fR handle will be in UTF\-8 mode.  And secondly,
+if the source is being read from perl's standard input then the \f(CW\*(C`DATA\*(C'\fR
+file handle is actually aliased to the \f(CW\*(C`STDIN\*(C'\fR file handle, and may
+be in UTF\-8 mode because of the \f(CW\*(C`PERL_UNICODE\*(C'\fR environment variable or
+perl's command-line switches.
+.PP
+See SelfLoader for more description of _\|_DATA_\|_, and
+an example of its use.  Note that you cannot read from the DATA
+filehandle in a BEGIN block: the BEGIN block is executed as soon
+as it is seen (during compilation), at which point the corresponding
+_\|_DATA_\|_ (or _\|_END_\|_) token has not yet been seen.
+.PP
+\fIBarewords\fR
+.IX Xref "bareword"
+.IX Subsection "Barewords"
+.PP
+A word that has no other interpretation in the grammar will
+be treated as if it were a quoted string.  These are known as
+"barewords".  As with filehandles and labels, a bareword that consists
+entirely of lowercase letters risks conflict with future reserved
+words, and if you use the \f(CW\*(C`use warnings\*(C'\fR pragma or the \fB\-w\fR switch, 
+Perl will warn you about any such words.  Perl limits barewords (like
+identifiers) to about 250 characters.  Future versions of Perl are likely
+to eliminate these arbitrary limitations.
+.PP
+Some people may wish to outlaw barewords entirely.  If you
+say
+.PP
+.Vb 1
+\&    use strict \*(Aqsubs\*(Aq;
+.Ve
+.PP
+then any bareword that would NOT be interpreted as a subroutine call
+produces a compile-time error instead.  The restriction lasts to the
+end of the enclosing block.  An inner block may countermand this
+by saying \f(CW\*(C`no strict \*(Aqsubs\*(Aq\*(C'\fR.
+.PP
+\fIArray Interpolation\fR
+.IX Xref "array, interpolation interpolation, array $"""
+.IX Subsection "Array Interpolation"
+.PP
+Arrays and slices are interpolated into double-quoted strings
+by joining the elements with the delimiter specified in the \f(CW$"\fR
+variable (\f(CW$LIST_SEPARATOR\fR if "use English;" is specified), 
+space by default.  The following are equivalent:
+.PP
+.Vb 2
+\&    $temp = join($", @ARGV);
+\&    system "echo $temp";
+\&
+\&    system "echo @ARGV";
+.Ve
+.PP
+Within search patterns (which also undergo double-quotish substitution)
+there is an unfortunate ambiguity:  Is \f(CW\*(C`/$foo[bar]/\*(C'\fR to be interpreted as
+\&\f(CW\*(C`/${foo}[bar]/\*(C'\fR (where \f(CW\*(C`[bar]\*(C'\fR is a character class for the regular
+expression) or as \f(CW\*(C`/${foo[bar]}/\*(C'\fR (where \f(CW\*(C`[bar]\*(C'\fR is the subscript to array
+\&\f(CW@foo\fR)?  If \f(CW@foo\fR doesn't otherwise exist, then it's obviously a
+character class.  If \f(CW@foo\fR exists, Perl takes a good guess about \f(CW\*(C`[bar]\*(C'\fR,
+and is almost always right.  If it does guess wrong, or if you're just
+plain paranoid, you can force the correct interpretation with curly
+braces as above.
+.PP
+If you're looking for the information on how to use here-documents,
+which used to be here, that's been moved to
+"Quote and Quote-like Operators" in perlop.
+.SS "List value constructors"
+.IX Xref "list"
+.IX Subsection "List value constructors"
+List values are denoted by separating individual values by commas
+(and enclosing the list in parentheses where precedence requires it):
+.PP
+.Vb 1
+\&    (LIST)
+.Ve
+.PP
+In a context not requiring a list value, the value of what appears
+to be a list literal is simply the value of the final element, as
+with the C comma operator.  For example,
+.PP
+.Vb 1
+\&    @foo = (\*(Aqcc\*(Aq, \*(Aq\-E\*(Aq, $bar);
+.Ve
+.PP
+assigns the entire list value to array \f(CW@foo\fR, but
+.PP
+.Vb 1
+\&    $foo = (\*(Aqcc\*(Aq, \*(Aq\-E\*(Aq, $bar);
+.Ve
+.PP
+assigns the value of variable \f(CW$bar\fR to the scalar variable \f(CW$foo\fR.
+Note that the value of an actual array in scalar context is the
+length of the array; the following assigns the value 3 to \f(CW$foo:\fR
+.PP
+.Vb 2
+\&    @foo = (\*(Aqcc\*(Aq, \*(Aq\-E\*(Aq, $bar);
+\&    $foo = @foo;                # $foo gets 3
+.Ve
+.PP
+You may have an optional comma before the closing parenthesis of a
+list literal, so that you can say:
+.PP
+.Vb 5
+\&    @foo = (
+\&        1,
+\&        2,
+\&        3,
+\&    );
+.Ve
+.PP
+To use a here-document to assign an array, one line per element,
+you might use an approach like this:
+.PP
+.Vb 7
+\&    @sauces = <<End_Lines =~ m/(\eS.*\eS)/g;
+\&        normal tomato
+\&        spicy tomato
+\&        green chile
+\&        pesto
+\&        white wine
+\&    End_Lines
+.Ve
+.PP
+LISTs do automatic interpolation of sublists.  That is, when a LIST is
+evaluated, each element of the list is evaluated in list context, and
+the resulting list value is interpolated into LIST just as if each
+individual element were a member of LIST.  Thus arrays and hashes lose their
+identity in a LIST\-\-the list
+.PP
+.Vb 1
+\&    (@foo,@bar,&SomeSub,%glarch)
+.Ve
+.PP
+contains all the elements of \f(CW@foo\fR followed by all the elements of \f(CW@bar\fR,
+followed by all the elements returned by the subroutine named SomeSub 
+called in list context, followed by the key/value pairs of \f(CW%glarch\fR.
+To make a list reference that does \fINOT\fR interpolate, see perlref.
+.PP
+The null list is represented by ().  Interpolating it in a list
+has no effect.  Thus ((),(),()) is equivalent to ().  Similarly,
+interpolating an array with no elements is the same as if no
+array had been interpolated at that point.
+.PP
+This interpolation combines with the facts that the opening
+and closing parentheses are optional (except when necessary for
+precedence) and lists may end with an optional comma to mean that
+multiple commas within lists are legal syntax.  The list \f(CW\*(C`1,,3\*(C'\fR is a
+concatenation of two lists, \f(CW\*(C`1,\*(C'\fR and \f(CW3\fR, the first of which ends
+with that optional comma.  \f(CW\*(C`1,,3\*(C'\fR is \f(CW\*(C`(1,),(3)\*(C'\fR is \f(CW\*(C`1,3\*(C'\fR (And
+similarly for \f(CW\*(C`1,,,3\*(C'\fR is \f(CW\*(C`(1,),(,),3\*(C'\fR is \f(CW\*(C`1,3\*(C'\fR and so on.)  Not that
+we'd advise you to use this obfuscation.
+.PP
+A list value may also be subscripted like a normal array.  You must
+put the list in parentheses to avoid ambiguity.  For example:
+.PP
+.Vb 2
+\&    # Stat returns list value.
+\&    $time = (stat($file))[8];
+\&
+\&    # SYNTAX ERROR HERE.
+\&    $time = stat($file)[8];  # OOPS, FORGOT PARENTHESES
+\&
+\&    # Find a hex digit.
+\&    $hexdigit = (\*(Aqa\*(Aq,\*(Aqb\*(Aq,\*(Aqc\*(Aq,\*(Aqd\*(Aq,\*(Aqe\*(Aq,\*(Aqf\*(Aq)[$digit\-10];
+\&
+\&    # A "reverse comma operator".
+\&    return (pop(@foo),pop(@foo))[0];
+.Ve
+.PP
+Lists may be assigned to only when each element of the list
+is itself legal to assign to:
+.PP
+.Vb 1
+\&    ($x, $y, $z) = (1, 2, 3);
+\&
+\&    ($map{\*(Aqred\*(Aq}, $map{\*(Aqblue\*(Aq}, $map{\*(Aqgreen\*(Aq}) = (0x00f, 0x0f0, 0xf00);
+.Ve
+.PP
+An exception to this is that you may assign to \f(CW\*(C`undef\*(C'\fR in a list.
+This is useful for throwing away some of the return values of a
+function:
+.PP
+.Vb 1
+\&    ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
+.Ve
+.PP
+As of Perl 5.22, you can also use \f(CW\*(C`(undef)x2\*(C'\fR instead of \f(CW\*(C`undef, undef\*(C'\fR.
+(You can also do \f(CW\*(C`($x) x 2\*(C'\fR, which is less useful, because it assigns to
+the same variable twice, clobbering the first value assigned.)
+.PP
+When you assign a list of scalars to an array, all previous values in that
+array are wiped out and the number of elements in the array will now be equal to
+the number of elements in the right-hand list \-\- the list from which
+assignment was made.  The array will automatically resize itself to precisely
+accommodate each element in the right-hand list.
+.PP
+.Vb 2
+\&    use warnings;
+\&    my (@xyz, $x, $y, $z);
+\&
+\&    @xyz = (1, 2, 3);
+\&    print "@xyz\en";                             # 1 2 3
+\&
+\&    @xyz = (\*(Aqal\*(Aq, \*(Aqbe\*(Aq, \*(Aqga\*(Aq, \*(Aqde\*(Aq);
+\&    print "@xyz\en";                             # al be ga de
+\&
+\&    @xyz = (101, 102);
+\&    print "@xyz\en";                             # 101 102
+.Ve
+.PP
+When, however, you assign a list of scalars to another list of scalars, the
+results differ according to whether the left-hand list \-\- the list being
+assigned to \-\- has the same, more or fewer elements than the right-hand list.
+.PP
+.Vb 2
+\&    ($x, $y, $z) = (1, 2, 3);
+\&    print "$x $y $z\en";                         # 1 2 3
+\&
+\&    ($x, $y, $z) = (\*(Aqal\*(Aq, \*(Aqbe\*(Aq, \*(Aqga\*(Aq, \*(Aqde\*(Aq);
+\&    print "$x $y $z\en";                         # al be ga
+\&
+\&    ($x, $y, $z) = (101, 102);
+\&    print "$x $y $z\en";                         # 101 102
+\&    # Use of uninitialized value $z in concatenation (.)
+\&    # or string at [program] line [line number].
+.Ve
+.PP
+If the number of scalars in the left-hand list is less than that in the
+right-hand list, the "extra" scalars in the right-hand list will simply not be
+assigned.
+.PP
+If the number of scalars in the left-hand list is greater than that in the
+left-hand list, the "missing" scalars will become undefined.
+.PP
+.Vb 6
+\&    ($x, $y, $z) = (101, 102);
+\&    for my $el ($x, $y, $z) {
+\&        (defined $el) ? print "$el " : print "<undef>";
+\&    }
+\&    print "\en";
+\&                                                # 101 102 <undef>
+.Ve
+.PP
+List assignment in scalar context returns the number of elements
+produced by the expression on the right side of the assignment:
+.PP
+.Vb 2
+\&    $x = (($foo,$bar) = (3,2,1));       # set $x to 3, not 2
+\&    $x = (($foo,$bar) = f());           # set $x to f()\*(Aqs return count
+.Ve
+.PP
+This is handy when you want to do a list assignment in a Boolean
+context, because most list functions return a null list when finished,
+which when assigned produces a 0, which is interpreted as FALSE.
+.PP
+It's also the source of a useful idiom for executing a function or
+performing an operation in list context and then counting the number of
+return values, by assigning to an empty list and then using that
+assignment in scalar context.  For example, this code:
+.PP
+.Vb 1
+\&    $count = () = $string =~ /\ed+/g;
+.Ve
+.PP
+will place into \f(CW$count\fR the number of digit groups found in \f(CW$string\fR.
+This happens because the pattern match is in list context (since it
+is being assigned to the empty list), and will therefore return a list
+of all matching parts of the string.  The list assignment in scalar
+context will translate that into the number of elements (here, the
+number of times the pattern matched) and assign that to \f(CW$count\fR.  Note
+that simply using
+.PP
+.Vb 1
+\&    $count = $string =~ /\ed+/g;
+.Ve
+.PP
+would not have worked, since a pattern match in scalar context will
+only return true or false, rather than a count of matches.
+.PP
+The final element of a list assignment may be an array or a hash:
+.PP
+.Vb 2
+\&    ($x, $y, @rest) = split;
+\&    my($x, $y, %rest) = @_;
+.Ve
+.PP
+You can actually put an array or hash anywhere in the list, but the first one
+in the list will soak up all the values, and anything after it will become
+undefined.  This may be useful in a \fBmy()\fR or \fBlocal()\fR.
+.PP
+A hash can be initialized using a literal list holding pairs of
+items to be interpreted as a key and a value:
+.PP
+.Vb 2
+\&    # same as map assignment above
+\&    %map = (\*(Aqred\*(Aq,0x00f,\*(Aqblue\*(Aq,0x0f0,\*(Aqgreen\*(Aq,0xf00);
+.Ve
+.PP
+While literal lists and named arrays are often interchangeable, that's
+not the case for hashes.  Just because you can subscript a list value like
+a normal array does not mean that you can subscript a list value as a
+hash.  Likewise, hashes included as parts of other lists (including
+parameters lists and return lists from functions) always flatten out into
+key/value pairs.  That's why it's good to use references sometimes.
+.PP
+It is often more readable to use the \f(CW\*(C`=>\*(C'\fR operator between key/value
+pairs.  The \f(CW\*(C`=>\*(C'\fR operator is mostly just a more visually distinctive
+synonym for a comma, but it also arranges for its left-hand operand to be
+interpreted as a string if it's a bareword that would be a legal simple
+identifier.  \f(CW\*(C`=>\*(C'\fR doesn't quote compound identifiers, that contain
+double colons.  This makes it nice for initializing hashes:
+.PP
+.Vb 5
+\&    %map = (
+\&                 red   => 0x00f,
+\&                 blue  => 0x0f0,
+\&                 green => 0xf00,
+\&   );
+.Ve
+.PP
+or for initializing hash references to be used as records:
+.PP
+.Vb 5
+\&    $rec = {
+\&                witch => \*(AqMable the Merciless\*(Aq,
+\&                cat   => \*(AqFluffy the Ferocious\*(Aq,
+\&                date  => \*(Aq10/31/1776\*(Aq,
+\&    };
+.Ve
+.PP
+or for using call-by-named-parameter to complicated functions:
+.PP
+.Vb 7
+\&   $field = $query\->radio_group(
+\&               name      => \*(Aqgroup_name\*(Aq,
+\&               values    => [\*(Aqeenie\*(Aq,\*(Aqmeenie\*(Aq,\*(Aqminie\*(Aq],
+\&               default   => \*(Aqmeenie\*(Aq,
+\&               linebreak => \*(Aqtrue\*(Aq,
+\&               labels    => \e%labels
+\&   );
+.Ve
+.PP
+Note that just because a hash is initialized in that order doesn't
+mean that it comes out in that order.  See "sort" in perlfunc for examples
+of how to arrange for an output ordering.
+.PP
+If a key appears more than once in the initializer list of a hash, the last
+occurrence wins:
+.PP
+.Vb 7
+\&    %circle = (
+\&                  center => [5, 10],
+\&                  center => [27, 9],
+\&                  radius => 100,
+\&                  color => [0xDF, 0xFF, 0x00],
+\&                  radius => 54,
+\&    );
+\&
+\&    # same as
+\&    %circle = (
+\&                  center => [27, 9],
+\&                  color => [0xDF, 0xFF, 0x00],
+\&                  radius => 54,
+\&    );
+.Ve
+.PP
+This can be used to provide overridable configuration defaults:
+.PP
+.Vb 2
+\&    # values in %args take priority over %config_defaults
+\&    %config = (%config_defaults, %args);
+.Ve
+.SS Subscripts
+.IX Subsection "Subscripts"
+An array can be accessed one scalar at a
+time by specifying a dollar sign (\f(CW\*(C`$\*(C'\fR), then the
+name of the array (without the leading \f(CW\*(C`@\*(C'\fR), then the subscript inside
+square brackets.  For example:
+.PP
+.Vb 2
+\&    @myarray = (5, 50, 500, 5000);
+\&    print "The Third Element is", $myarray[2], "\en";
+.Ve
+.PP
+The array indices start with 0.  A negative subscript retrieves its 
+value from the end.  In our example, \f(CW$myarray[\-1]\fR would have been 
+5000, and \f(CW$myarray[\-2]\fR would have been 500.
+.PP
+Hash subscripts are similar, only instead of square brackets curly brackets
+are used.  For example:
+.PP
+.Vb 7
+\&    %scientists = 
+\&    (
+\&        "Newton" => "Isaac",
+\&        "Einstein" => "Albert",
+\&        "Darwin" => "Charles",
+\&        "Feynman" => "Richard",
+\&    );
+\&
+\&    print "Darwin\*(Aqs First Name is ", $scientists{"Darwin"}, "\en";
+.Ve
+.PP
+You can also subscript a list to get a single element from it:
+.PP
+.Vb 1
+\&    $dir = (getpwnam("daemon"))[7];
+.Ve
+.SS "Multi-dimensional array emulation"
+.IX Subsection "Multi-dimensional array emulation"
+Multidimensional arrays may be emulated by subscripting a hash with a
+list.  The elements of the list are joined with the subscript separator
+(see "$;" in perlvar).
+.PP
+.Vb 1
+\&    $foo{$x,$y,$z}
+.Ve
+.PP
+is equivalent to
+.PP
+.Vb 1
+\&    $foo{join($;, $x, $y, $z)}
+.Ve
+.PP
+The default subscript separator is "\e034", the same as SUBSEP in \fBawk\fR.
+.SS Slices
+.IX Xref "slice array, slice hash, slice"
+.IX Subsection "Slices"
+A slice accesses several elements of a list, an array, or a hash
+simultaneously using a list of subscripts.  It's more convenient
+than writing out the individual elements as a list of separate
+scalar values.
+.PP
+.Vb 4
+\&    ($him, $her)   = @folks[0,\-1];              # array slice
+\&    @them          = @folks[0 .. 3];            # array slice
+\&    ($who, $home)  = @ENV{"USER", "HOME"};      # hash slice
+\&    ($uid, $dir)   = (getpwnam("daemon"))[2,7]; # list slice
+.Ve
+.PP
+Since you can assign to a list of variables, you can also assign to
+an array or hash slice.
+.PP
+.Vb 4
+\&    @days[3..5]    = qw/Wed Thu Fri/;
+\&    @colors{\*(Aqred\*(Aq,\*(Aqblue\*(Aq,\*(Aqgreen\*(Aq} 
+\&                   = (0xff0000, 0x0000ff, 0x00ff00);
+\&    @folks[0, \-1]  = @folks[\-1, 0];
+.Ve
+.PP
+The previous assignments are exactly equivalent to
+.PP
+.Vb 4
+\&    ($days[3], $days[4], $days[5]) = qw/Wed Thu Fri/;
+\&    ($colors{\*(Aqred\*(Aq}, $colors{\*(Aqblue\*(Aq}, $colors{\*(Aqgreen\*(Aq})
+\&                   = (0xff0000, 0x0000ff, 0x00ff00);
+\&    ($folks[0], $folks[\-1]) = ($folks[\-1], $folks[0]);
+.Ve
+.PP
+Since changing a slice changes the original array or hash that it's
+slicing, a \f(CW\*(C`foreach\*(C'\fR construct will alter some\-\-or even all\-\-of the
+values of the array or hash.
+.PP
+.Vb 1
+\&    foreach (@array[ 4 .. 10 ]) { s/peter/paul/ } 
+\&
+\&    foreach (@hash{qw[key1 key2]}) {
+\&        s/^\es+//;                       # trim leading whitespace
+\&        s/\es+$//;                       # trim trailing whitespace
+\&        s/\eb(\ew)(\ew*)\eb/\eu$1\eL$2/g;     # "titlecase" words
+\&    }
+.Ve
+.PP
+As a special exception, when you slice a list (but not an array or a hash),
+if the list evaluates to empty, then taking a slice of that empty list will
+always yield the empty list in turn.  Thus:
+.PP
+.Vb 6
+\&    @a = ()[0,1];          # @a has no elements
+\&    @b = (@a)[0,1];        # @b has no elements
+\&    @c = (sub{}\->())[0,1]; # @c has no elements
+\&    @d = (\*(Aqa\*(Aq,\*(Aqb\*(Aq)[0,1];   # @d has two elements
+\&    @e = (@d)[0,1,8,9];    # @e has four elements
+\&    @f = (@d)[8,9];        # @f has two elements
+.Ve
+.PP
+This makes it easy to write loops that terminate when a null list
+is returned:
+.PP
+.Vb 3
+\&    while ( ($home, $user) = (getpwent)[7,0] ) {
+\&        printf "%\-8s %s\en", $user, $home;
+\&    }
+.Ve
+.PP
+As noted earlier in this document, the scalar sense of list assignment
+is the number of elements on the right-hand side of the assignment.
+The null list contains no elements, so when the password file is
+exhausted, the result is 0, not 2.
+.PP
+Slices in scalar context return the last item of the slice.
+.PP
+.Vb 4
+\&    @a = qw/first second third/;
+\&    %h = (first => \*(AqA\*(Aq, second => \*(AqB\*(Aq);
+\&    $t = @a[0, 1];                  # $t is now \*(Aqsecond\*(Aq
+\&    $u = @h{\*(Aqfirst\*(Aq, \*(Aqsecond\*(Aq};     # $u is now \*(AqB\*(Aq
+.Ve
+.PP
+If you're confused about why you use an '@' there on a hash slice
+instead of a '%', think of it like this.  The type of bracket (square
+or curly) governs whether it's an array or a hash being looked at.
+On the other hand, the leading symbol ('$' or '@') on the array or
+hash indicates whether you are getting back a singular value (a
+scalar) or a plural one (a list).
+.PP
+\fIKey/Value Hash Slices\fR
+.IX Subsection "Key/Value Hash Slices"
+.PP
+Starting in Perl 5.20, a hash slice operation
+with the % symbol is a variant of slice operation
+returning a list of key/value pairs rather than just values:
+.PP
+.Vb 6
+\&    %h = (blonk => 2, foo => 3, squink => 5, bar => 8);
+\&    %subset = %h{\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq}; # key/value hash slice
+\&    # %subset is now (foo => 3, bar => 8)
+\&    %removed = delete %h{\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq};
+\&    # %removed is now (foo => 3, bar => 8)
+\&    # %h is now (blonk => 2, squink => 5)
+.Ve
+.PP
+However, the result of such a slice cannot be localized or assigned to.
+These are otherwise very much consistent with hash slices
+using the @ symbol.
+.PP
+\fIIndex/Value Array Slices\fR
+.IX Subsection "Index/Value Array Slices"
+.PP
+Similar to key/value hash slices (and also introduced
+in Perl 5.20), the % array slice syntax returns a list
+of index/value pairs:
+.PP
+.Vb 6
+\&    @a = "a".."z";
+\&    @list = %a[3,4,6];
+\&    # @list is now (3, "d", 4, "e", 6, "g")
+\&    @removed = delete %a[3,4,6]
+\&    # @removed is now (3, "d", 4, "e", 6, "g")
+\&    # @list[3,4,6] are now undef
+.Ve
+.PP
+Note that calling \f(CW\*(C`delete\*(C'\fR on array values is
+strongly discouraged.
+.SS "Typeglobs and Filehandles"
+.IX Xref "typeglob filehandle *"
+.IX Subsection "Typeglobs and Filehandles"
+Perl uses an internal type called a \fItypeglob\fR to hold an entire
+symbol table entry.  The type prefix of a typeglob is a \f(CW\*(C`*\*(C'\fR, because
+it represents all types.  This used to be the preferred way to
+pass arrays and hashes by reference into a function, but now that
+we have real references, this is seldom needed.
+.PP
+The main use of typeglobs in modern Perl is create symbol table aliases.
+This assignment:
+.PP
+.Vb 1
+\&    *this = *that;
+.Ve
+.PP
+makes \f(CW$this\fR an alias for \f(CW$that\fR, \f(CW@this\fR an alias for \f(CW@that\fR, \f(CW%this\fR an alias
+for \f(CW%that\fR, &this an alias for &that, etc.  Much safer is to use a reference.
+This:
+.PP
+.Vb 1
+\&    local *Here::blue = \e$There::green;
+.Ve
+.PP
+temporarily makes \f(CW$Here::blue\fR an alias for \f(CW$There::green\fR, but doesn't
+make \f(CW@Here::blue\fR an alias for \f(CW@There::green\fR, or \f(CW%Here::blue\fR an alias for
+\&\f(CW%There::green\fR, etc.  See "Symbol Tables" in perlmod for more examples
+of this.  Strange though this may seem, this is the basis for the whole
+module import/export system.
+.PP
+Another use for typeglobs is to pass filehandles into a function or
+to create new filehandles.  If you need to use a typeglob to save away
+a filehandle, do it this way:
+.PP
+.Vb 1
+\&    $fh = *STDOUT;
+.Ve
+.PP
+or perhaps as a real reference, like this:
+.PP
+.Vb 1
+\&    $fh = \e*STDOUT;
+.Ve
+.PP
+See perlsub for examples of using these as indirect filehandles
+in functions.
+.PP
+Typeglobs are also a way to create a local filehandle using the \fBlocal()\fR
+operator.  These last until their block is exited, but may be passed back.
+For example:
+.PP
+.Vb 7
+\&    sub newopen {
+\&        my $path = shift;
+\&        local  *FH;  # not my!
+\&        open   (FH, $path)          or  return undef;
+\&        return *FH;
+\&    }
+\&    $fh = newopen(\*(Aq/etc/passwd\*(Aq);
+.Ve
+.PP
+Now that we have the \f(CW*foo{THING}\fR notation, typeglobs aren't used as much
+for filehandle manipulations, although they're still needed to pass brand
+new file and directory handles into or out of functions.  That's because
+\&\f(CW*HANDLE{IO}\fR only works if HANDLE has already been used as a handle.
+In other words, \f(CW*FH\fR must be used to create new symbol table entries;
+\&\f(CW*foo{THING}\fR cannot.  When in doubt, use \f(CW*FH\fR.
+.PP
+All functions that are capable of creating filehandles (\fBopen()\fR,
+\&\fBopendir()\fR, \fBpipe()\fR, \fBsocketpair()\fR, \fBsysopen()\fR, \fBsocket()\fR, and \fBaccept()\fR)
+automatically create an anonymous filehandle if the handle passed to
+them is an uninitialized scalar variable.  This allows the constructs
+such as \f(CW\*(C`open(my $fh, ...)\*(C'\fR and \f(CW\*(C`open(local $fh,...)\*(C'\fR to be used to
+create filehandles that will conveniently be closed automatically when
+the scope ends, provided there are no other references to them.  This
+largely eliminates the need for typeglobs when opening filehandles
+that must be passed around, as in the following example:
+.PP
+.Vb 5
+\&    sub myopen {
+\&        open my $fh, "@_"
+\&             or die "Can\*(Aqt open \*(Aq@_\*(Aq: $!";
+\&        return $fh;
+\&    }
+\&
+\&    {
+\&        my $f = myopen("</etc/motd");
+\&        print <$f>;
+\&        # $f implicitly closed here
+\&    }
+.Ve
+.PP
+Note that if an initialized scalar variable is used instead the
+result is different: \f(CW\*(C`my $fh=\*(Aqzzz\*(Aq; open($fh, ...)\*(C'\fR is equivalent
+to \f(CW\*(C`open( *{\*(Aqzzz\*(Aq}, ...)\*(C'\fR.
+\&\f(CW\*(C`use strict \*(Aqrefs\*(Aq\*(C'\fR forbids such practice.
+.PP
+Another way to create anonymous filehandles is with the Symbol
+module or with the IO::Handle module and its ilk.  These modules
+have the advantage of not hiding different types of the same name
+during the \fBlocal()\fR.  See the bottom of "open" in perlfunc for an
+example.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See perlvar for a description of Perl's built-in variables and
+a discussion of legal variable names.  See perlref, perlsub,
+and "Symbol Tables" in perlmod for more discussion on typeglobs and
+the \f(CW*foo{THING}\fR syntax.