X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/a5effbbc577ce192c131f5cd79c2af95064ac714..e57270be442bfaa9dc23eebd67485e5a806b44e3:/pod/perlvar.pod
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index add3756..09ec06d 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -12,30 +12,30 @@ arbitrarily long (up to an internal limit of 251 characters) and
may contain letters, digits, underscores, or the special sequence
C<::> or C<'>. In this case, the part before the last C<::> or
C<'> is taken to be a I; see L.
-
-Perl variable names may also be a sequence of digits or a single
-punctuation or control character. These names are all reserved for
+A Unicode letter that is not ASCII is not considered to be a letter
+unless S> is in effect, and somewhat more complicated
+rules apply; see L for details.
+
+Perl variable names may also be a sequence of digits, a single
+punctuation character, or the two-character sequence: C<^> (caret or
+CIRCUMFLEX ACCENT) followed by any one of the characters C<[][A-Z^_?\]>.
+These names are all reserved for
special uses by Perl; for example, the all-digits names are used
to hold data captured by backreferences after a regular expression
-match. Perl has a special syntax for the single-control-character
-names: It understands C<^X> (caret C) to mean the control-C
-character. For example, the notation C<$^W> (dollar-sign caret
-C) is the scalar variable whose name is the single character
-control-C. This is better than typing a literal control-C
-into your program.
-
-Since Perl v5.6.0, Perl variable names may be alphanumeric
-strings that begin with control characters (or better yet, a caret).
-These variables must be written in the form C<${^Foo}>; the braces
-are not optional. C<${^Foo}> denotes the scalar variable whose
-name is a control-C followed by two C's. These variables are
+match.
+
+Since Perl v5.6.0, Perl variable names may also be alphanumeric strings
+preceded by a caret. These must all be written in the form C<${^Foo}>;
+the braces are not optional. C<${^Foo}> denotes the scalar variable
+whose name is considered to be a control-C followed by two C's.
+These variables are
reserved for future special uses by Perl, except for the ones that
-begin with C<^_> (control-underscore or caret-underscore). No
-control-character name that begins with C<^_> will acquire a special
+begin with C<^_> (caret-underscore). No
+name that begins with C<^_> will acquire a special
meaning in any future version of Perl; such names may therefore be
used safely in programs. C<$^_> itself, however, I reserved.
-Perl identifiers that begin with digits, control characters, or
+Perl identifiers that begin with digits or
punctuation characters are exempt from the effects of the C
declaration and are always forced to be in package C; they are
also exempt from C errors. A few other names are also
@@ -165,7 +165,7 @@ X<@_> X<@ARG>
Within a subroutine the array C<@_> contains the parameters passed to
that subroutine. Inside a subroutine, C<@_> is the default array for
-the array operators C, C, C, and C.
+the array operators C and C.
See L.
@@ -370,19 +370,19 @@ X<$;> X<$SUBSEP> X
The subscript separator for multidimensional array emulation. If you
refer to a hash element as
- $foo{$a,$b,$c}
+ $foo{$x,$y,$z}
it really means
- $foo{join($;, $a, $b, $c)}
+ $foo{join($;, $x, $y, $z)}
But don't put
- @foo{$a,$b,$c} # a slice--note the @
+ @foo{$x,$y,$z} # a slice--note the @
which means
- ($foo{$a},$foo{$b},$foo{$c})
+ ($foo{$x},$foo{$y},$foo{$z})
Default is "\034", the same as SUBSEP in B. If your keys contain
binary data there might not be any safe value for C<$;>.
@@ -410,14 +410,14 @@ The hash C<%ENV> contains your current environment. Setting a
value in C changes the environment for any child processes
you subsequently C off.
-As of 5.17.3, both keys and values stored in C<%ENV> are stringified.
+As of v5.18.0, both keys and values stored in C<%ENV> are stringified.
my $foo = 1;
$ENV{'bar'} = \$foo;
if( ref $ENV{'bar'} ) {
- say "Pre 5.17.3 Behaviour";
+ say "Pre 5.18.0 Behaviour";
} else {
- say "Post 5.17.3 Behaviour";
+ say "Post 5.18.0 Behaviour";
}
Previously, only child processes received stringified values:
@@ -426,11 +426,51 @@ Previously, only child processes received stringified values:
$ENV{'bar'} = \$foo;
# Always printed 'non ref'
- system($^X,'-e',q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /);
+ system($^X, '-e',
+ q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /);
This happens because you can't really share arbitrary data structures with
foreign processes.
+=item $OLD_PERL_VERSION
+
+=item $]
+X<$]> X<$OLD_PERL_VERSION>
+
+The revision, version, and subversion of the Perl interpreter, represented
+as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY
+is the subversion / 1e6. For example, Perl v5.10.1 would be "5.010001".
+
+This variable can be used to determine whether the Perl interpreter
+executing a script is in the right range of versions:
+
+ warn "No PerlIO!\n" if $] lt '5.008';
+
+When comparing C<$]>, string comparison operators are B. The inherent limitations of binary floating point
+representation can sometimes lead to incorrect comparisons for some
+numbers on some architectures.
+
+See also the documentation of C
match operator flag and the
-C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> variables instead
-so you only suffer the performance penalties.
+In Perl 5.10.0 the C match operator flag and the C<${^PREMATCH}>,
+C<${^MATCH}>, and C<${^POSTMATCH}> variables were introduced, that allowed
+you to suffer the penalties only on patterns marked with C.
-If you are using Perl v5.20.0 or higher, you do not need to worry about
-this, as the three naughty variables are no longer naughty.
+In Perl 5.18.0 onwards, perl started noting the presence of each of the
+three variables separately, and only copied that part of the string
+required; so in
+
+ $`; $&; "abcdefgh" =~ /d/
+
+perl would only copy the "abcd" part of the string. That could make a big
+difference in something like
+
+ $str = 'x' x 1_000_000;
+ $&; # whoops
+ $str =~ /x/g # one char copied a million times, not a million chars
+
+In Perl 5.20.0 a new copy-on-write system was enabled by default, which
+finally fixes all performance issues with these three variables, and makes
+them safe to use anywhere.
+
+The C and C modules can help you
+find uses of these problematic match variables in your code.
=over 8
@@ -833,12 +913,8 @@ The string matched by the last successful pattern match (not counting
any matches hidden within a BLOCK or C enclosed by the current
BLOCK).
-In Perl v5.18 and earlier, the use of this variable
-anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. To avoid this
-penalty, you can extract the same substring by using L@->. Starting
-with Perl v5.10.0, you can use the C match flag and the C<${^MATCH}>
-variable to do the same thing for particular match operations.
+See L above for the serious performance implications
+of using this variable (even once) in your code.
This variable is read-only and dynamically-scoped.
@@ -849,6 +925,9 @@ X<${^MATCH}>
This is similar to C<$&> (C<$MATCH>) except that it does not incur the
performance penalty associated with that variable.
+
+See L above.
+
In Perl v5.18 and earlier, it is only guaranteed
to return a defined value when the pattern was compiled or executed with
the C modifier. In Perl v5.20, the C modifier does nothing, so
@@ -867,13 +946,8 @@ The string preceding whatever was matched by the last successful
pattern match, not counting any matches hidden within a BLOCK or C
enclosed by the current BLOCK.
-In Perl v5.18 and earlier, the use of this variable
-anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. To avoid this
-penalty, you can extract the same substring by using L@->. Starting
-with Perl v5.10.0, you can use the C match flag and the
-C<${^PREMATCH}> variable to do the same thing for particular match
-operations.
+See L above for the serious performance implications
+of using this variable (even once) in your code.
This variable is read-only and dynamically-scoped.
@@ -884,12 +958,15 @@ X<$`> X<${^PREMATCH}>
This is similar to C<$`> ($PREMATCH) except that it does not incur the
performance penalty associated with that variable.
+
+See L above.
+
In Perl v5.18 and earlier, it is only guaranteed
to return a defined value when the pattern was compiled or executed with
the C modifier. In Perl v5.20, the C modifier does nothing, so
C<${^PREMATCH}> does the same thing as C<$PREMATCH>.
-This variable was added in Perl v5.10.0
+This variable was added in Perl v5.10.0.
This variable is read-only and dynamically-scoped.
@@ -906,13 +983,8 @@ enclosed by the current BLOCK). Example:
/def/;
print "$`:$&:$'\n"; # prints abc:def:ghi
-In Perl v5.18 and earlier, the use of this variable
-anywhere in a program imposes a considerable
-performance penalty on all regular expression matches.
-To avoid this penalty, you can extract the same substring by
-using L@->. Starting with Perl v5.10.0, you can use the C match flag
-and the C<${^POSTMATCH}> variable to do the same thing for particular
-match operations.
+See L above for the serious performance implications
+of using this variable (even once) in your code.
This variable is read-only and dynamically-scoped.
@@ -923,6 +995,9 @@ X<${^POSTMATCH}> X<$'> X<$POSTMATCH>
This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
performance penalty associated with that variable.
+
+See L above.
+
In Perl v5.18 and earlier, it is only guaranteed
to return a defined value when the pattern was compiled or executed with
the C modifier. In Perl v5.20, the C modifier does nothing, so
@@ -1060,10 +1135,8 @@ After a match against some variable C<$var>:
This variable was added in Perl v5.6.0.
-=item %LAST_MATCH_START
-
=item %-
-X<%-> X<%LAST_MATCH_START>
+X<%->
Similar to C<%+>, this variable allows access to the named capture groups
in the last successful match in the currently active dynamic scope. To
@@ -1373,7 +1446,12 @@ not reading from a record-oriented file (or your OS doesn't have
record-oriented files), then you'll likely get a full chunk of data
with every read. If a record is larger than the record size you've
set, you'll get the record back in pieces. Trying to set the record
-size to zero or less will cause reading in the (rest of the) whole file.
+size to zero or less is deprecated and will cause $/ to have the value
+of "undef", which will cause reading in the (rest of the) whole file.
+
+As of 5.19.9 setting C<$/> to any other form of reference will throw a
+fatal exception. This is in preparation for supporting new ways to set
+C<$/> in the future.
On VMS only, record reads bypass PerlIO layers and any associated
buffering, so you must not mix record and non-record reads on the
@@ -1589,12 +1667,12 @@ Under a few operating systems, C<$^E> may contain a more verbose error
indicator, such as in this case, "CDROM tray not closed." Systems that
do not support extended error messages leave C<$^E> the same as C<$!>.
-Finally, C<$?> may be set to non-0 value if the external program
+Finally, C<$?> may be set to a non-0 value if the external program
F fails. The upper eight bits reflect specific error
conditions encountered by the program (the program's C value).
The lower eight bits reflect mode of failure, like signal death and
core dump information. See L for details. In contrast to
-C<$!> and C<$^E>, which are set only if error condition is detected,
+C<$!> and C<$^E>, which are set only if an error condition is detected,
the variable C<$?> is set on each C or pipe C,
overwriting the old value. This is more like C<$@>, which on every
C is always set on failure and cleared on success.
@@ -1742,10 +1820,12 @@ Each element of C<%!> has a true value only if C<$!> is set to that
value. For example, C<$!{ENOENT}> is true if and only if the current
value of C<$!> is C; that is, if the most recent error was "No
such file or directory" (or its moral equivalent: not all operating
-systems give that exact error, and certainly not all languages). To
-check if a particular key is meaningful on your system, use C; for a list of legal keys, use C. See L
-for more information, and also see L$!>.
+systems give that exact error, and certainly not all languages). The
+specific true value is not guaranteed, but in the past has generally
+been the numeric value of C<$!>. To check if a particular key is
+meaningful on your system, use C; for a list of legal
+keys, use C. See L for more information, and also see
+L$!>.
This variable was added in Perl 5.005.
@@ -1787,17 +1867,18 @@ Mnemonic: similar to B and B.
=item $@
X<$@> X<$EVAL_ERROR>
-The Perl syntax error message from the
-last C operator. If C<$@> is
-the null string, the last C parsed and executed correctly
-(although the operations you invoked may have failed in the normal
-fashion).
+The Perl error from the last C operator, i.e. the last exception that
+was caught. For C, this is either a runtime error message or the
+string or reference C was called with. The C form also
+catches syntax errors and other compile time exceptions.
+
+If no error occurs, C sets C<$@> to the empty string.
Warning messages are not collected in this variable. You can, however,
set up a routine to process warnings by setting C<$SIG{__WARN__}> as
described in L%SIG>.
-Mnemonic: Where was the syntax error "at"?
+Mnemonic: Where was the error "at"?
=back
@@ -1834,10 +1915,34 @@ Mnemonic: value of B<-D> switch.
=item ${^ENCODING}
X<${^ENCODING}>
+DEPRECATED!!!
+
The I