From 0b9346e662b8f4423806dc42a8098704eebcae7b Mon Sep 17 00:00:00 2001
From: brian d foy
Date: Sun, 24 Oct 2010 01:58:08 -0500
Subject: I think I have perlvar ordered and proper now
---
pod/perlvar.pod | 682 ++++++++++++++++++++++++++++----------------------------
1 file changed, 343 insertions(+), 339 deletions(-)
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index f3cc7dcb7c..9acdcfc8e3 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -6,45 +6,45 @@ perlvar - Perl predefined variables
=head2 The Syntax of Variable Names
-Variable names in Perl can have several formats. Usually, they
+Variable names in Perl can have several formats. Usually, they
must begin with a letter or underscore, in which case they can be
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<::> 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
+punctuation or control character. 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
+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
+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
+control-C. This is better than typing a literal control-C
into your program.
Since Perl 5.6, 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
+are not optional. C<${^Foo}> denotes the scalar variable whose
+name is 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
+begin with C<^_> (control-underscore or caret-underscore). No
control-character 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.
+used safely in programs. C<$^_> itself, however, I reserved.
Perl identifiers that begin with digits, control characters, 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
+also exempt from C errors. A few other names are also
exempt in these ways:
- ENV STDIN
- INC STDOUT
- ARGV STDERR
- ARGVOUT _
+ ENV STDIN
+ INC STDOUT
+ ARGV STDERR
+ ARGVOUT
SIG
In particular, the special C<${^_XYZ}> variables are always taken
@@ -53,12 +53,11 @@ presently in scope.
=head1 SPECIAL VARIABLES
-The following names have special meaning to Perl. Most punctuation
-names have reasonable mnemonics, or analogs in the shells.
-Nevertheless, if you wish to use long variable names, you need only
-say
+The following names have special meaning to Perl. Most punctuation
+names have reasonable mnemonics, or analogs in the shells.
+Nevertheless, if you wish to use long variable names, you need only say:
- use English;
+ use English;
at the top of your program. This aliases all the short names to the long
names in the current package. Some even have medium names, generally
@@ -66,13 +65,14 @@ borrowed from B. To avoid a performance hit, if you don't need the
C<$PREMATCH>, C<$MATCH>, or C<$POSTMATCH> it's best to use the C
module without them:
- use English '-no_match_vars';
+ use English '-no_match_vars';
-Before you continue, note the sort order for variables. In general, we first list
-the variables in order of their type, scalars first, then arrays and hashes, followed
-by the odd barewords (i.e. filehandles). Within each variable type, we sort the
-names in lexicographical order. However, C<$_> gets pride of place since its
-extra special.
+Before you continue, note the sort order for variables. In general, we
+first list the variables in case-insensitive, almost-lexigraphical
+order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}>
+or C<$^T>), although C<$_> and C<@_> move up to the top of the pile.
+For variables with the same identifier, we list it in order of scalar,
+array, hash, and bareword.
=head2 General Variables
@@ -86,20 +86,19 @@ X<$_> X<$ARG>
The default input and pattern-searching space. The following pairs are
equivalent:
- while (<>) {...} # equivalent only in while!
- while (defined($_ = <>)) {...}
+ while (<>) {...} # equivalent only in while!
+ while (defined($_ = <>)) {...}
- /^Subject:/
- $_ =~ /^Subject:/
+ /^Subject:/
+ $_ =~ /^Subject:/
- tr/a-z/A-Z/
- $_ =~ tr/a-z/A-Z/
+ tr/a-z/A-Z/
+ $_ =~ tr/a-z/A-Z/
- chomp
- chomp($_)
+ chomp
+ chomp($_)
-Here are the places where Perl will assume C<$_> even if you
-don't use it:
+Here are the places where Perl will assume C<$_> even if you don't use it:
=over 3
@@ -118,7 +117,6 @@ unlink, unpack.
All file tests (C<-f>, C<-d>) except for C<-t>, which defaults to STDIN.
See L
-
=item *
The pattern matching operations C, C and C
(aka C)
@@ -152,48 +150,16 @@ declaring C restores the global C<$_> in the current scope.
Mnemonic: underline is understood in certain operations.
-=item $a
-
-=item $b
-X<$a> X<$b>
-
-Special package variables when using C, see L.
-Because of this specialness C<$a> and C<$b> don't need to be declared
-(using C
match operator flag and the
+C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> variables instead
+so you only suffer the performance penalties.
+
=over 8
=item $> ($1, $2, ...)
@@ -972,16 +986,15 @@ any matches hidden within a BLOCK or C enclosed by the current
BLOCK).
The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. See L.
-To avoid this penatly, you can extract the same substring by
-using L@->. Starting with Perl 5.10, you can use the match flag
-and the C<${^MATCH}> variable to do the same thing for particular
-match operations.
+performance penalty on all regular expression matches. To avoid this
+penalty, you can extract the same substring by using L@->. Starting
+with Perl 5.10, you can use the match flag and the C<${^MATCH}>
+variable to do the same thing for particular match operations.
This variable is read-only and dynamically-scoped.
Mnemonic: like C<&> in some editors.
-
+
=item ${^MATCH}
X<${^MATCH}>
@@ -1001,14 +1014,14 @@ X<$`> X<$PREMATCH>
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.
+enclosed by the current BLOCK.
The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. See L.
-To avoid this penatly, you can extract the same substring by
-using L@->. Starting with Perl 5.10, you can use the match flag
-and the C<${^PREMATCH}> variable to do the same thing for particular
-match operations.
+performance penalty on all regular expression matches. To avoid this
+penalty, you can extract the same substring by using L@->. Starting
+with Perl 5.10, you can use the match flag and the
+C<${^PREMATCH}> variable to do the same thing for particular match
+operations.
This variable is read-only and dynamically-scoped.
@@ -1035,15 +1048,15 @@ The string following whatever was matched by the last successful
pattern match (not counting any matches hidden within a BLOCK or C
enclosed by the current BLOCK). Example:
- local $_ = 'abcdefghi';
- /def/;
- print "$`:$&:$'\n"; # prints abc:def:ghi
+ local $_ = 'abcdefghi';
+ /def/;
+ print "$`:$&:$'\n"; # prints abc:def:ghi
The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. See L.
-To avoid this penatly, you can extract the same substring by
+performance penalty on all regular expression matches.
+To avoid this penalty, you can extract the same substring by
using L@->. Starting with Perl 5.10, you can use the match flag
-and the C<${^POSTMATCH}> variable to do the same thing for particular
+and the C<${^POSTMATCH}> variable to do the same thing for particular
match operations.
This variable is read-only and dynamically-scoped.
@@ -1071,7 +1084,7 @@ The text matched by the last bracket of the last successful search pattern.
This is useful if you don't know which one of a set of alternative patterns
matched. For example:
- /Version: (.*)|Revision: (.*)/ && ($rev = $+);
+ /Version: (.*)|Revision: (.*)/ && ($rev = $+);
This variable is read-only and dynamically-scoped.
@@ -1090,7 +1103,7 @@ This is primarily used inside C<(?{...})> blocks for examining text
recently matched. For example, to effectively capture text to a variable
(in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
- (?:(...)(?{ $var = $^N }))
+ (?:(...)(?{ $var = $^N }))
By setting and then using C<$var> in this way relieves you from having to
worry about exactly which numbered set of parentheses they are.
@@ -1128,7 +1141,7 @@ currently active dynamic scope.
For example, C<$+{foo}> is equivalent to C<$1> after the following match:
- 'foo' =~ /(?foo)/;
+ 'foo' =~ /(?foo)/;
The keys of the C<%+> hash list only the names of buffers that have
captured (and that are thus associated to defined values).
@@ -1215,10 +1228,10 @@ Here's an example:
would print out:
- $-{A}[0] : '1'
- $-{A}[1] : '3'
- $-{B}[0] : '2'
- $-{B}[1] : '4'
+ $-{A}[0] : '1'
+ $-{A}[1] : '3'
+ $-{B}[0] : '2'
+ $-{B}[1] : '4'
The keys of the C<%-> hash correspond to all buffer names found in
the regular expression.
@@ -1275,15 +1288,15 @@ although this is less efficient than using the regular built-in
variables. (Summary lines below for this contain the word HANDLE.)
First you must say
- use IO::Handle;
+ use IO::Handle;
after which you may use either
- method HANDLE EXPR
+ method HANDLE EXPR
or more safely,
- HANDLE->method(EXPR)
+ HANDLE->method(EXPR)
Each method returns the old value of the C attribute. The
methods each take an optional EXPR, which, if supplied, specifies the
@@ -1305,17 +1318,17 @@ the change may affect other modules which rely on the default values
of the special variables that you have changed. This is one of the
correct ways to read the whole file at once:
- open my $fh, "<", "foo" or die $!;
- local $/; # enable localized slurp mode
- my $content = <$fh>;
- close $fh;
+ open my $fh, "<", "foo" or die $!;
+ local $/; # enable localized slurp mode
+ my $content = <$fh>;
+ close $fh;
But the following code is quite bad:
- open my $fh, "<", "foo" or die $!;
- undef $/; # enable slurp mode
- my $content = <$fh>;
- close $fh;
+ open my $fh, "<", "foo" or die $!;
+ undef $/; # enable slurp mode
+ my $content = <$fh>;
+ close $fh;
since some other module, may want to read data from some file in the
default "line mode", so if the code we have just presented has been
@@ -1327,37 +1340,41 @@ change affects the shortest scope possible. So unless you are already
inside some short C<{}> block, you should create one yourself. For
example:
- my $content = '';
- open my $fh, "<", "foo" or die $!;
- {
- local $/;
- $content = <$fh>;
- }
- close $fh;
+ my $content = '';
+ open my $fh, "<", "foo" or die $!;
+ {
+ local $/;
+ $content = <$fh>;
+ }
+ close $fh;
Here is an example of how your own code can go broken:
- for (1..5){
- nasty_break();
- print "$_ ";
- }
- sub nasty_break {
- $_ = 5;
- # do something with $_
- }
+ for ( 1..3 ){
+ $\ = "\r\n";
+ nasty_break();
+ print "$_";
+ }
+
+ sub nasty_break {
+ $\ = "\f";
+ # do something with $_
+ }
-You probably expect this code to print:
+You probably expect this code to print the equivalent of
- 1 2 3 4 5
+ "1\r\n2\r\n3\r\n"
but instead you get:
- 5 5 5 5 5
+ "1\f2\f3\f"
-Why? Because C modifies C<$_> without localizing it
-first. The fix is to add C:
+Why? Because C modifies C<$\> without localizing it
+first. The value you set in C is still there when you
+return. The fix is to add C so the value doesn't leak out of
+C:
- local $_ = 5;
+ local $\ = "\f";
It's easy to notice the problem in such a short example, but in more
complicated code you are looking for trouble if you don't localize
@@ -1672,12 +1689,12 @@ After execution of this statement all 4 variables may have been set.
C<$@> is set if the string to be C-ed did not compile (this may
happen if C or C were imported with bad prototypes), or
-if Perl code executed during evaluation die()d . In these cases the
-value of $@ is the compile error, or the argument to C (which
+if Perl code executed during evaluation Cd . In these cases the
+value of C<$@> is the compile error, or the argument to C (which
will interpolate C<$!> and C<$?>). (See also L, though.)
-When the C expression above is executed, C, C<<
->>, and C are translated to calls in the C run-time library and
+When the C expression above is executed, C, C<< >>,
+and C are translated to calls in the C run-time library and
thence to the operating system kernel. C<$!> is set to the C library's
C if one of these calls fails.
@@ -1698,6 +1715,8 @@ C is always set on failure and cleared on success.
For more details, see the individual descriptions at C<$@>, C<$!>,
C<$^E>, and C<$?>.
+=over 8
+
=item $EXTENDED_OS_ERROR
=item ${^CHILD_ERROR_NATIVE}
@@ -1742,7 +1761,7 @@ C<$^E>, also.
This variable was added in Perl 5.003.
Mnemonic: Extra error explanation.
-
+
=item $EXCEPTIONS_BEING_CAUGHT
=item $^S
@@ -1771,7 +1790,7 @@ used, false otherwise, but directly modifiable.
See also L.
-Mnemonic: related to the B<-w> switch.
+Mnemonic: related to the B<-w> switch.
=item ${^WARNING_BITS}
@@ -1870,8 +1889,8 @@ Mnemonic: similar to B and B.
=item $@
X<$@> X<$EVAL_ERROR>
-The Perl syntax error message from the last eval() operator. If $@ is
-the null string, the last eval() parsed and executed correctly
+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).
@@ -1885,7 +1904,7 @@ Mnemonic: Where was the syntax error "at"?
=head2 Deprecated and removed variables
-Deprecating a variable announces the intent of the perl maintainers to
+Deprecating a variable announces the intent of the perl maintainers to
eventually remove the variable from the langauge. It may still be
available despite its status. Using a deprecated variable triggers
a warning.
@@ -1930,13 +1949,13 @@ X<$[>
This variable stores the index of the first element in an array, and
of the first character in a substring. You use to be able to assign to
this variable, but you can't do that anymore. It's now always 0, like
-God intended.
+it should be.
Mnemonic: [ begins subscripts.
This variable is read-only.
-Deprecated in Perl 5.12.
+Deprecated in Perl 5.12.
=item $]
X<$]>
@@ -1960,19 +1979,4 @@ Deprecated in Perl 5.6.
=back
-=head1 BUGS
-
-Due to an unfortunate accident of Perl's implementation, C